HumanGate

You should know what your coding agents are doing. Push your agent to walk you through the code line by line!

Why this exists

A coding agent can write a thousand lines before lunch. Reading them is the slow part, and it usually happens once, in a chat window, and is then forgotten. A week later the agent edits a function you had already checked, and nothing tells you.

HumanGate is a VS Code extension that turns "did a human actually read this?" into something you can see and keep:

• It walks you through your project one small piece at a time: a function, a notebook cell, a section of a paper.
• Your own Claude Code explains each piece on a card: what it does, what breaks if it is wrong, what to watch out for.
• You approve, defer, ask, or request a change. Your verdicts are saved in the repo.
• When approved code changes later, by you, by an agent, or while VS Code was closed, that approval is withdrawn automatically and the piece comes back for another look.

You stay the gate. The agent does the explaining.

What you need

• VS Code 1.104 or newer.
• The Claude Code extension for VS Code, installed and signed in. HumanGate runs the Claude Code that comes with it, with your login. No API key, nothing to configure.
• Edge or Chrome, for the card window. (Your default browser is used if neither is found.)
• Optional: the Python extension if you review notebooks, so cells can be split by function.

Install

HumanGate is not on the Marketplace yet. Build the package once and install it:

# in a clone of this repository
npm install
npx @vscode/vsce package --skip-license
code --install-extension humangate-*.vsix

Then run Developer: Reload Window in VS Code. If a .vsix is attached to a release on GitHub, you can download that instead and skip the first two commands.

Your first review

1. Open your project in VS Code and run HumanGate: Start Review from the command palette (Ctrl+Shift+P). A separate window opens.

2. Choose what to review. Tick the folders and file types that matter. Folders like docs and examples start unticked, and git-ignored files are left out. Nothing is read before you press Start review.

   

3. The agent reads the code, works out a sensible reading order (entry points first, helpers last), and shows you the first card. This takes a moment the first time.

4. Read the code on the card and decide:

   Button	Key	What it does
   Approve	a	You read it and it is fine. On to the next card.
   Defer	d	You cannot decide yet. Give a reason; the card goes into the cart for later.
   Change	c	Describe what should be different. A stronger model makes the edit and shows you the result.
   Deep check	k	Ask the stronger model to look hard for bugs. Its findings appear beside the card.
   Next	n	Skip for now. The card comes back after the rest.

5. Close the window whenever you like. Your progress is saved; Start Review picks up where you stopped.

While you read one card, the next one is already being prepared, so Approve usually shows it instantly.

Getting more out of a card

• Ask anything. The panel on the right is a conversation about this card. Type a question, get a plain answer, follow up. The conversation is saved with the card.

• Right-click the code. Select some lines, right-click, and choose Ask about these lines or Explain in comments (the agent writes short comments into your file at exactly those lines; comments never cost you an approval).

  

• Follow a call without leaving the card. Function names that the code calls are links. Click one and that function opens right under the line, like a peek in VS Code.

• Long functions stay whole. A function is never cut into several cards. If it is long, its inner blocks start folded so you see the shape first; click to open them. Approve reminds you once if you never opened some.

  

• Jump around. The top bar says card 62 of 63. The number is a box: type a card number, or part of a file, function or title, and press Enter.

• The code is live. The card shows your file as it is right now. Edit and save in VS Code and the card follows.

The cart: "I can't decide this yet"

Some things need a full run, real data, or the bigger picture. Press Defer, say why, and keep reading. Deferred cards collect in the cart at the bottom left with your reasons.

When you are ready, click an entry to reopen its card, or press Have the agent check all: the agent looks into every reason and reports on each card. Approving a deferred card takes it out of the cart.

When every piece is approved or deferred, you get a Review complete screen with the totals.

Not only code

• Jupyter notebooks are reviewed cell by cell, in place. Nothing is converted. Running a notebook never costs an approval, because only the code of a cell counts, not its output. Edits the agent makes go into the cell and leave outputs and other cells alone.

  

• Markdown and LaTeX are shown rendered, with formulas typeset and your own LaTeX macros understood, so a paper reads like a paper. Switch to Source any time.

  

When code changes behind your back

This is the part that makes approvals worth something.

• Change an approved function, and its approval is gone the moment you save. Comments and blank lines do not count.
• If another tool or agent edits files while VS Code is closed, HumanGate notices on the next start. It compares a fingerprint of every file, which is quick even on a big project.
• The changed pieces come back at the end of your walk, as cards that show when you approved them, which lines are new, and which approved lines are gone.
• The Approve button refuses if the file changed while you were reading.

Want to start over? Change scope → Reset all cards forgets every approval (a backup of the old ledger is kept).

Letting the agent run code (off by default)

Out of the box the agent can only read, and every change it makes comes back to you as a card. It has no shell.

If you want it to check things by running them ("what does this return for an empty list?"), open Models in the top bar and tick Let the agent run code. It can then run only commands that start with an entry of your list, such as python, pytest or node. Anything else is refused.

Be aware that python can do whatever a program can do. The agent is told to run and look, never to change files, and any file that did change would lose its approval like any other edit. Leave this off if you are reviewing code you do not trust.

What it costs

HumanGate uses your Claude Code subscription or API plan, like any other Claude Code session. The top bar shows what the review has used so far. A few things keep it low:

• Every card is written once and kept. Coming back to a card, restarting VS Code, or a colleague reviewing the same unchanged code costs nothing.
• When the next cards are already written, the agent is not even started.
• Questions are answered in a short message; the card is never rewritten for them.
• Cards and answers use a fast model (sonnet, low effort). Only Change and Deep check use the stronger one (opus). Both are yours to choose under Models.
• Closing the card window stops the agent after ten seconds.

Your data

• Everything runs on your machine. The card window is a local page served by the extension; nothing is sent anywhere except what Claude Code itself sends to Anthropic, under your account and its usual terms.
• HumanGate keeps its state in a .humangate/ folder in your project: the ledger of verdicts, the texts you approved, the cards, your conversations and the cart. It is plain JSON. Commit it if you want approvals to travel with the repo; add it to .gitignore if you do not.
• Text from your files is never run as script in the card window, even if a Markdown file tries.

Settings

All optional. Search for "HumanGate" in VS Code's settings.

Setting	Default	What it is for
humangate.model / humangate.effort	sonnet / low	Model and effort for cards and answers
humangate.reviseModel / humangate.reviseEffort	opus / high	Model and effort for Change and Deep check
humangate.allowRun	off	Let the agent run code
humangate.runCommands	python, pytest, node, ...	Which commands it may run
humangate.lineCap	60	Roughly how many lines of top-level code go on one card
humangate.include / humangate.exclude	code files / build folders	What can be reviewed at all
humangate.claudePath	(automatic)	A different Claude Code executable
humangate.port	7331	Local port of the card window

If something looks wrong

• The window says "Agent stopped". That is fine: it sleeps when it has nothing to write. Press Resume, or just click a verdict.
• No first card appears. Open VS Code's Output panel and pick HumanGate. The usual cause is that the Claude Code extension is not installed or not signed in.
• A notebook cell is one big card. Install the Python extension; cells are then split by function.
• I approved something by mistake. Put the cursor in that code in VS Code and run HumanGate: Mark Span Unverified. It comes back as a card.
• I want to see everything that is left. The HumanGate icon in VS Code's activity bar lists every piece and its state.

Good to know

• One workspace folder at a time.
• Renaming a function, or moving it to another file, makes it a new piece: its approval does not follow.
• The "changed since approval" marks compare lines, not a full diff, so moved lines are not highlighted.
• The ledger is a plain file. A tool that edits .humangate/ledger.json directly could fake an approval, so look at changes to that file like any other.
• Edge or Chrome, and the Claude Code binary inside its VS Code extension, are found by their usual install paths. On Linux, HumanGate falls back to claude on your PATH and your default browser.

For the curious, and for contributors

• docs/reference.md: how everything works in detail, from hashing to the agent's tools.
• docs/design-brief.md: the original idea.
• docs/development-log.md: what was built, in order, and why.

npm test                 # unit tests
npm run e2e              # real VS Code, a scripted stand-in for the agent
npm run visual           # screenshots and a browser-driven check of the card window
npm run smoke            # a short review with your real Claude Code (uses your quota)

Contributors

• JOHNDST: idea, design decisions, review.
• Claude Code: wrote most of the code and tests, working with the author. Its commits carry a Co-Authored-By: Claude line.

Built with KaTeX, marked, highlight.js and the MCP TypeScript SDK.

License and disclaimer

MIT. See LICENSE.

HumanGate is an independent project. It is not made, endorsed or supported by Anthropic. It drives the Claude Code you installed, with your own login, through Claude Code's documented command-line interface.