The problem
An AI agent will happily write two hundred lines of code from a requirement nobody read carefully.
That was the failure I kept hitting. The agent wasn't bad at coding — it was good at it, which was the problem. It would take a vague line in a spec, interpret it confidently, and produce something plausible, structured, and wrong. By the time the mistake was visible it had spread across a dozen files, and unpicking it cost more than writing the thing by hand would have.
The specs were the weak link, and nobody was reviewing them. We review code obsessively — a two-line change gets a pull request, comments, a second pair of eyes. Then we hand an AI a paragraph of prose nobody has read twice and let it generate the diff.
Why I built it
Review the spec the way you review code.
Not "read it over" — actually review it. Comment on line 12. Say this is ambiguous before it becomes 200 lines of confident nonsense. Refine it in place. The spec is the artifact the AI works from, so the spec is the artifact that deserves the review.
Two things I deliberately did not build.
Not a chat interface. Chat is the wrong shape for this. It's ephemeral, it has no anchor to a specific line, and it leaves no artifact you can commit. I wanted the opposite: durable, positional, reviewable.
Not another agent. There are plenty, and betting on one would have meant betting against the rest. Companion dispatches to ten providers today — Claude Code, Gemini, Copilot, Codex, Qwen, OpenCode, Wibey, IDE chat, and more — and takes custom phases and commands on top. It's a workspace, not an assistant.
It also didn't start from nothing. The first version grew out of kiro-for-cc, which had the seed of the idea. What I added was the review layer, the lifecycle capture, and the provider fan-out.
How it works
A feature moves through phases — Specify, Plan, Tasks, Done. The extension renders each one, tracks where it is, and dispatches the next step to whichever AI you've chosen.
Three decisions carried most of the weight.
No database. The files are the truth. There's no extension-owned store hiding beside your repo. The spec files on disk are the single source of truth, which means the terminal and the GUI are never competing — they're two front-ends over one set of files. Drive a step from the terminal and the viewer reflects it on the next change; drive it from the viewer and your terminal sees the same files. Neither owns the workflow. That property is worth more than any feature I could have built on top of a private database.
The extension never reads the AI's answer. Its only coupling to a provider is dispatching command text. It assembles a prompt, hands it to a terminal or the editor's chat, and stops. It doesn't parse responses, doesn't install anyone's CLI, doesn't try to be smart about what came back. Keeping that boundary thin is why supporting the tenth provider cost about as much as the third.
Honest about what it can't measure. Lifecycle capture comes from two sources, and they are not equally reliable. Deterministic writes — you clicked a button, a hook fired — are exact to the millisecond. AI self-journaling is best-effort, because an agent narrating its own work is guessing. I could have blended these into one confident-looking timeline. Instead they're tagged separately and the coarse ones are labelled coarse. A tool that overstates its own precision is worse than one that admits the gap.
That principle has teeth elsewhere too. The task checkboxes are derived from the event log rather than hand-edited, so the two can't diverge. And the AI never edits the context file directly — it calls a writer script that stamps the clock and writes atomically. Hand-authoring was what corrupted the file in practice.
Results
- ~28,000 installs across the VS Code Marketplace and Open VSX.
- 526 commits since 2 December 2025; 47 releases, currently v0.28.
- 1,228 tests across 86 test files.
- Ten AI providers, plus bring-your-own workflows.
- Four outside contributors. MIT licensed.
I also benchmarked it honestly, and published the result even though it isn't flattering. Building the same features through stock SpecKit and through Companion, at three difficulty levels: Companion's specs came out 60–68% leaner and it wrote zero throwaway side files, but it was slower on the easy and medium cases and only pulled ahead on the hard one. Correctness was a tie — every build in both workflows passed. The honest summary is the one in the README: the difference is ceremony and progress visibility, not whether the feature works.
What I'd do differently
I ran a full code-quality audit on my own project in May, and it found four things. I'm going to just quote myself, because softening it would be the wrong move.
"Half-finished Preact migration." Components mounted on top of a still-live imperative DOM pipeline, with three independent rendering systems coordinating on the same DOM. That's the structural fire, it's still burning, and it exists because I migrated incrementally without ever committing to finishing. Incremental migration is good advice right up to the point where you stop, and then you own two systems instead of one.
"Eight providers, no shared base class." Roughly 700–900 lines of copy-paste, because each provider independently reimplemented temp-file writes, shell escaping, and terminal lifecycle. I knew it was duplicated by the third one. I kept going anyway because each individual copy was faster than the abstraction would have been. The abstraction exists now; it should have existed at provider three.
"Docs lie about the codebase." The architecture doc claimed five providers when there were eight, listed files that no longer existed, and omitted the entire Preact rewrite. The fix wasn't to rewrite the doc — it was to make the doc testable. There's now a test that fails on every run if a path the docs mention disappears, or if a new provider is added without a doc mention. Documentation you can't test is documentation that's already wrong.
One more, and it's the one I'd most want a reviewer to notice: I tried a rewrite, and reverted it. I replaced the imperative toast queue with a declarative signal-driven version, couldn't match the existing animation timing without regressions, and put the old one back. The audit had flagged it as a problem; the audit was speculative and there was exactly one caller. Knowing when the refactor isn't worth it is a skill, and I only learned it by spending the afternoon.