How it works

gx adds a context layer around your existing Git workflow. It captures what happened during coding sessions, attaches that context to ordinary Git commits, and reads it back during review.

Everything below runs on your machine. There is no gx server, no account, and no per-seat feature behind any of it.

The problem

Git was built for humans typing commits one at a time. A commit stores a snapshot and a short message, and for human-paced work that is usually enough.

Agent-written code breaks two of Git's assumptions:

1. The context that explains a change never makes it into the repo. The prompt that asked for the change, the commands the agent ran, the tests it executed, the dead ends it backed out of — all of that lives in a session transcript that is gone by review time. The commit message is whatever one line survived.
2. Review is now the bottleneck. The cost of generating code is dropping toward zero, but teams still review line by line. When a pull request is one large undifferentiated diff with a thin message, the reviewer reconstructs intent from scratch.

What gx captures

• Sessions — transcripts from Claude Code, Codex, and Cursor, captured into ~/.gx/gx.db. This happens entirely locally; there is nothing to publish to.
• Revisions — each plain git commit is recorded as one reviewable unit, down to individual hunks, and stamped with a gx-revision: trailer. That trailer is how a revision is found again later — it is an index, not a link.

Where capture stops and retrieval starts

This is the honest boundary, and it is worth being explicit about it.

Capturing a session needs nothing. Reading one back during gx review needs an index to search, and gx searches a vector store. With no index configured, the session, code-index, and review-knowledge retrievers report themselves disabled and the review runs without them — no error, no warning banner, just less context than a configured install sees.

So in a stock local install:

Everything the review decides is available either way. What an index buys is recall: the ability to answer "where else does this pattern appear" and "what did we decide last time about this file". gx index builds one, and it needs OPENAI_API_KEY plus a vector store to write to.

How gx review works

gx review reads the current change — a dirty working tree, or the branch's commits against its base — and reviews it with two independent AI reviewers plus repo context: the indexed codebase, captured sessions, review history, and your repo's review policy. A judge model then verifies and dedupes the findings. Alongside them it runs what the project already has — the compiler, the linter, the test suite, a secret scan over added lines, and the dependency audits when a manifest moved — and reports those results as evidence rather than as a separate command.

Findings land in two lanes, and the split is what makes the verdict worth trusting. A finding is blocking only when both reviewers raised it independently and the verification model confirmed it; anything one model raised alone is advisory — reported, but it will not stop you. Agreement between independent readers is the strongest confidence signal a panel produces, so gx spends it on the only decision that matters: ship or don't.

The run ends in that verdict — SHIP, NO-SHIP, DEGRADED when the panel could not fully run, or NOTHING-TO-REVIEW. Because a pass is a claim about code that was actually inspected, the last two cases are failures rather than quiet zeros.

The command touches no Git state — no hooks, no commits, no index mutation, and no ~/.gx on a machine that never ran gx init — so it runs anywhere, including CI (the exit code gates by default) and checkouts you do not own. The one file it writes is the report itself, saved to review/ and added to your local Git excludes so it never shows up as a change. See the CLI reference.

Why this speeds up review

• The verdict tells you whether the change is safe to ship before it becomes someone else's problem.
• A finding blocks only on agreement from independent reviewers plus confirmation from a third, which is what makes a NO-SHIP worth listening to.
• Session provenance answers "why is this here?" without a round-trip to whoever wrote the prompt — when an index is configured, the prompt, commands, and tests are part of the review context.
• gx review catches findings before the PR exists, when they are cheapest to fix.

Everything is still just Git

The hooks stamp plain git commit messages and never block a push. Your repository does not become gx-specific in any way that outlives the binary: stop using gx tomorrow and your branches, commits, and pull requests are ordinary Git. Session capture writes to ~/.gx and goes nowhere else.