HellionChat/docs/LEARNING-JOURNEY.md

Development History and Learning Process

Background

I am self-taught. Hellion Chat is my first FFXIV plugin and my first larger C# project. My professional background is web development (Next.js, React, TypeScript, Prisma, MySQL) — browser world with a JavaScript toolchain. I knew C# only superficially before this project, ImGui not at all, and Dalamud only as an end user through other plugins.

When I get stuck somewhere, I use AI tools like Claude Code as a pair assistant. What that looks like exactly and which classification I use is documented transparently in AI_DISCLOSURE.md.

---

Why a chat plugin at all?

Hellion Chat is not meant to replace Chat 2. Chat 2 delivers a complete chat experience with full history, filters, search and replay. For most users that is exactly the right thing.

Two million messages in two years

My desire for a tighter default was honestly personal at first. After two years with Chat 2 my database had grown to over two million messages, the majority of them /say, /shout and /yell from complete strangers in Limsa. That is exactly what makes Chat 2's full history useful, and most users are happy to keep it. My own preference wanted a smaller default. So I built this fork.

Greeter in several clubs

There was a second use case: I am active as a greeter in several FFXIV clubs. The vanilla chat interface is not enough for greeter work. Parallel /tell conversations write into a single tab at the same time, and I constantly lose track of who wrote what. Auto-Tell-Tabs (one of the early Hellion Chat features) came directly from this workflow: one tab per conversation partner, automatically spawned, with a manual greeted status. The privacy hygiene benefit was a nice bonus, not the trigger.

Hellion Online Media

The privacy defaults also reflect a position from my main work. Hellion Online Media is my sole proprietorship, and data protection toward clients is not a marketing slogan there but operationally relevant. This fork is the plugin form of the same stance.

---

Why not contribute to the original?

Three reasons, in descending order of importance.

Defaults are not negotiable, including mine

Privacy-first as a default is a minority position. Chat 2 rightly serves the broad majority with full history as the default. Changing those defaults upstream would have been wrong. I would have flipped the standard for a large user base that wanted it as it was. A clean separation through a dedicated plugin slot was the more respectful path.

The web interface had to go

It is a central Chat 2 feature for remote access from a second device. A PR removing it has no chance in a well-maintained upstream project, and that is correct. But exactly that web interface conflicts with the privacy-first premise of this fork: a chat plugin that starts a local HTTP server is too large an attack surface for my threat model. So out it went.

Velocity

A solo-maintainer project with a small tester pool can iterate faster than an established plugin with a large user base. That is not a criticism of upstream but a different optimization. I do not need roadmap alignment, reviewer availability, or to spread audit consequences like the web interface removal across multiple releases.

EUPL-1.2 explicitly allows all of this with clear attribution. The code is open under the same license as Chat 2. Infi, Anna, or anyone else can look in, take ideas, ask questions, or simply ignore the fork. All three are fine with me.

---

How I release this fast

Anyone looking at the repo sees a lot of releases and a high commit count in a short time. Both tend to read as red flags from the outside: AI slop, salami tactics, code spam. In Hellion Chat both are deliberate decisions, and I would rather explain them once than justify them later.

Groundwork, long before the fork existed

Before I typed the first line into HellionChat/, I spent weeks as a reader. Using Chat 2 in-game and playing around with it. Going through issues in the upstream tracker, especially the closed ones, because that is where you see how Infi and Anna narrow down bugs. Reading commits, including older ones, to understand why an architecture decision was made, not just that it was made. If I know today where things live in the codebase, it is not because I navigate codebases particularly fast but because I read the code beforehand.

That sounds obvious. It is not. The usual order for solo forks is fork first, understand later. I did it the other way around.

One thing I noticed reading the codebase closely: some patterns felt familiar in ways I had not expected, structural choices and comment styles that show up across a lot of modern plugin and tooling code regardless of how it was written. Nothing worth reading into. Coding workflows have changed a lot in the last few years across the board, and the traces of that show up everywhere. It did make me less self-conscious about my own workflow.

Infi and Anna's codebase

Hellion Chat builds on a foundation that is already flat. Chat 2 is cleanly structured, naming conventions are consistent, and the separation between layers (storage, UI, game hooks, IPC) is clearly drawn. That is not a given in open-source plugin land, and it is the main reason Hellion-specific features often slot in "almost natively". I do not have to untangle spaghetti before I can put something of my own next to it.

Side note: even during the first codebase walkthrough with Claude, the comment came up several times that the architecture is unusually tidy and has several extension points prepared. That carries weight because it comes from outside, but the actual credit goes to Infi and Anna, not Claude.

Atomic work, small commits

One commit, one logical change. If I fix a bug, rename a variable and add a comment at the same time, that is three commits, not one. Sounds like micro-management, it is not. If a bug surfaces in six months and I need git bisect, I find the broken change in two minutes instead of two hours. With a 4000-line mega-commit I get to guess which of the hundred changes is the broken one.

I kept this style deliberately also because Infi works the same way upstream. Sometimes a six-line commit, sometimes just a typo fix. That is not a weakness, it is a decision for readable Git history. Keeping the style in the fork is a respect move: anyone comparing both repos should have the same reading rhythm.

Personal bonus: small commits force me to think through and name each step individually. If I cannot explain what a commit does in two sentences, the change is probably not clear enough yet. At beginner level that is a built-in sanity check I would not have with a big-bang commit.

AI as an accelerator, honestly

Yes, AI helps with velocity, and not a little. Without CodeRabbit I would not have found critical bugs like Equals/GetHashCode anti-patterns, hook subscription leaks and TOCTOU races. I am simply too inexperienced for that class of findings, and I write that exactly as it is.

What I do not do: blindly take code because a tool marked it as a fix. On several CodeRabbit findings, the original commits from Infi or Anna even included a Stack Overflow link explaining why a particular spot looks the way it does. I read those before touching anything. Understand first, then change, then commit. That is the difference between "AI gives me code, I push" and "AI shows me where it breaks, I decide".

Classification and concrete examples of AI usage are in AI_DISCLOSURE.md. This section was only about the velocity aspect: research plus a clean codebase plus atomic commits plus AI-assisted review sparring are the four factors together. No single one explains the pace on its own.

---

From the web stack to C# / Dalamud

Type system? Less of a shock than expected

C# after TypeScript was more comfortable than expected. Properties instead of getters/setters are clean, nullable reference types feel like strict: true in TypeScript. What was unfamiliar was having to think explicitly about value types versus reference types (struct vs. class with real behavioural consequences), and generics with constraints are syntactically different enough that I stumble on them while reading. async/await is semantically similar, but threading models are more explicit in C#: Task.Run, ConfigureAwait, synchronization contexts. That cost me several bugs before I understood when the main thread (in plugin land: the framework tick) is actually critical.

Build toolchain: similar, but different

dotnet CLI, csproj XML, NuGet are functionally not far from npm and tsconfig. But the XML format of csproj is a different language than JSON configs. The lock file (packages.lock.json) had to be actively enabled (RestorePackagesWithLockFile=true); that is not the default. In the web stack, lock-file-first is standard, in the .NET stack apparently not. That was a real surprise.

ImGui is a different world

Immediate-mode rendering has nothing in common with React component trees. There is no virtual DOM, no reconciliation, no "component state". Every frame the code redraws the UI from scratch, and state lives either in local variables I manage myself or in ImGui's own ID stack logic.

What is two lines of useState in React is a member field plus manual ID stamps on widgets in ImGui, otherwise two selectables in the same loop collide because they fall back to the same ID. The ID stack collision in SearchSelector (fixed in v1.0.0) was exactly that symptom: all selectables fell back to the same ambiguous ID until I mixed the row index into the PushID. Classic "why is the wrong entry getting clicked" bug that you only find once you understand how ImGui handles IDs internally.

Dalamud specifics

Plugin lifecycle, IPC subscriber pattern, hook system for game functions, game object threading. Much of that was only understandable through reading the upstream codebase and through dalamud.dev. Search results for "Dalamud" often turn up outdated API examples from old versions. dalamud.dev is the reliable source. If someone is just starting out: go there, not to Stack Overflow.

The day DalamudPackager cost me a day

Dalamud SDK 15 ships its own default packager that writes icons and image URLs into the manifest. I had carried over a DalamudPackager.targets file from the upstream repo with a HandleImages override, and it was overriding the SDK default. Result: the manifest had no IconUrl anymore, and the plugin appeared in the plugin list without an icon.

The symptom was easy to spot, the cause cost a day. I had treated the override file as mandatory when it was not. Removed in v0.5.2, SDK default running since then. Lesson: start with defaults, add overrides only when the default demonstrably does not fit.

---

What I learned from the fork

Refactoring in an unfamiliar codebase

The standalone cut in v1.0.0 migrated the entire ChatTwo.* identity to HellionChat.*. That sounds like find and replace. It was not.

In concrete terms: code namespace across all 80 source files plus 100 using directives plus two FQN aliases plus the resource designer strings. Six IPC channels renamed (breaking change for third-party plugins, no known integrations). Repo folder structure (ChatTwo/ -> HellionChat/) including csproj, sln, all GitHub workflows and dependabot.yml. Public-facing branding in README, repo.json and yaml reformulated to standalone framing.

It was not a solo find-and-replace because Unicode string paths in workflow YAMLs need different quoting than C# strings. Because resource designer files have generated content that not every toolchain tracks. And because the ChatTwo.* IPC channel names are strings in GetIpcSubscriber calls: no symbol, no compile error if you miss one. That is when you find out what stays quiet.

Security is no longer abstract

Before this project, supply chain security was academic for me. Three concrete lessons changed that.

SQLite native binary. I had to pin to 3.50.3 (SQLitePCLRaw.lib.e_sqlite3 override) because Microsoft.Data.Sqlite was pulling in a transitively referenced library at a version containing CVE-2025-6965 (memory corruption via aggregate term overflow) and CVE-2025-7709. The managed wrapper was new; the native library was not. Lesson: transitive dependencies do not audit themselves, you have to look.

Lock file drift. packages.lock.json honoured via RestorePackagesWithLockFile=true in the csproj prevents transitive versions from silently drifting between my machine and CI. I only understood why this is not the default after a build output mismatch between local and GitHub Actions.

WrapText and the CodeQL alert that cost three releases. CodeQL flagged a critical alert in ImGuiUtil.WrapText for unvalidated local pointer arithmetic. v0.5.2 validated an edge case. Alert came back. v0.5.3 checked buffer length via GetByteCount before the pointer math. Alert came back. v0.5.4 rebuilt the whole algorithm on Span and int offsets with a 16 KiB cap on the ArrayPool rent. Only then did it go quiet.

Lesson: when a static analyser complains three times in a row, the analyser is not oversensitive. The data flow logic is.

CodeRabbit as an external code reviewer

The v1.0.0 sweep surfaced 3 critical and 21 major findings. Three classes were particularly instructive:

• Equals methods comparing GetHashCode(). Classic hash collision anti-pattern. Sounds like "if hashes are equal the objects are equal", which is exactly backwards. Hashes can collide; the objects are not equal.
• Dispose methods that only unsubscribe part of their subscriptions. Leak on every plugin reload. In normal use you do not notice it immediately; in a long-running test you do.
• TOCTOU races. Between a bounds check and a read another thread can swap out the array underneath you (GlobalParametersCache, AutoTranslate).

I had at best read the theory on all of these before, never diagnosed them in my own code. CodeRabbit was the moment where "academic knowledge" became "okay, that is my code, that is my bug".

External testers are worth their weight

Carla's feedback on pop-out discoverability triggered the header button in v0.6.1. That pop-outs were only reachable via right-click was something I as maintainer had stopped seeing; I knew the path by heart. Carl's request for theme variants with brightness gradations shifted my thinking from "one theme = one colour" to "theme families with mood variants". Jingliu asked for TempTell persistence, which puts the tab system architecturally into question.

Solo I would not have seen any of those three things. Full stop.

release.yml and the YAML rabbit hole

The release.yml workflow simply did not fire on the first v0.6.0 tag push. I dug through permissions, secret scopes and tag trigger configuration for hours before I understood what was actually happening: the PowerShell heredoc footer in the "Generate release body" step contained a --- Markdown horizontal rule at column 1, and that terminated the YAML block scalar of run: |. GitHub could not parse the workflow file, so the push-tag trigger never registered.

Fix: extracted the footer into an external .github/release-footer.md, workflow reads it via Get-Content. Lesson: if a workflow does not trigger, verify first that GitHub can even parse the file. That was one of the bugs where I laughed briefly after the fix and then asked myself how many other YAML files I had that might have the same trap in them.

---

What I am still learning

Performance profiling in a game context

The FPS drop bug from upstream Chat 2 (#145) has not been reproduced or verified in Hellion Chat. v1.0.0 applied several fixes on the suspected paths (DbViewer O(N²) -> O(N), AutoTranslate lock serialisation, EmoteCache HttpClient reuse), but systematic measurement under load is missing. I still need to learn how to properly measure what is actually consuming the frame budget in a plugin context.

Native interop and pointer math

Even after the WrapText Span refactor in v0.5.4, pointer math makes me uneasy. ImGui forces you into unsafe code in several places, and the safety margin from the "unbounded ArrayPool allocation" class of bugs is narrower than I would like. I want to get better at that before touching deeper ImGui custom drawing.

Test discipline for plugin code

The repo currently has no test project. That is a deliberate decision, not a forgotten one. Testing plugin code with FFXIV hooks and Dalamud lifecycle cleanly is non-trivial, and I had not found an approach that made sense without a large mocking scaffold. Privacy filter and configuration migration would be good test candidates because they are isolated. On the list, but not a quick win.

Linux quirks under Wine

XDG compliance, libnotify integration, WireGuard network detection, all on the roadmap, and all technically still unclear. Wine and sandboxed plugin code do not share all system APIs, and I do not know where the pitfalls are until I have found them.

---

Use of AI tools

I use Claude Code as an assistant, not as a replacement for my own work.

What I use AI for:

• Debugging problems where I am stuck after extended research of my own
• Pattern recognition across large codebases (e.g. the ChatTwo -> HellionChat sweep across 80 files)
• Understanding questions on C# and Dalamud concepts I am not yet familiar with
• Code review sparring before I run CodeRabbit on something

What I do myself:

• Architecture and design decisions
• Privacy-first defaults and the threat model behind them
• Tester communication and roadmap prioritisation
• Reviewing, verifying, pushing

Classification and concrete examples are in AI_DISCLOSURE.md. It matters to me that users and potential contributors understand how the code came together, especially for a plugin that handles user data.

Yes, AI. Yes, alone. Both mentioned more than strictly necessary. Welcome to the open-source plugin climate.

---

Why this transparency

Anyone reading the source code should know:

• I am not a professional C# or plugin developer and am still learning
• AI assistance is a tool, not a ghostwriter
• The privacy position, the design decisions and the roadmap are mine
• I try to keep my code as clean and secure as my current skills allow

Hellion Chat is also a learning project, and that should be visible in the repository.

---

Links

• AI_DISCLOSURE.md -- AI pair disclosure with classification schema
• CONTRIBUTORS.md -- who has made this plugin better alongside me
• ../NOTICE.md -- attribution to Infi and Anna for the Chat 2 foundation
• ROADMAP.md -- planned cycles and topics