Vantage

What is Vantage? (60 seconds)

Vantage runs on your own computer and shows how far each piece of your work has really got. When AI coding agents do much of the typing, it is easy to lose track of what was asked, what was built and what was actually tested. Vantage reads the traces your agents and git leave behind and draws one row per piece of work. A row moves forward only on evidence, such as a test that ran after the last edit. What an agent says never moves it. Nothing leaves your machine.

One example item, "add a retry to the uploader", moving along the track:

 Asked      Built       Proven       Reviewed    Shipped     Verified
   ●          ●           ◐            ○           ○           ○
 you asked  3 files     no test ran   waiting     not yet     not yet
            changed     after the edit

It sits at Built · no proof yet until a real test runs after the last edit; then the third dot fills in. New here? Read the plain-language guide, or run vantage tour, a guided, offline walkthrough (vantage tour --demo opens made-up data you can click around; see first run).

Learn more

All docs by audience: docs/README.md.

A personal, calm view of the true state of your work across AI coding agents, git, pull requests, CI/CD, monitoring, Jira or Linear, and Slack.

Vantage tracks work items, not sessions. Each item moves along one evidence-based track, the A2V track from the A2V: Asked to Verified method:

Asked → Built → Proven → Reviewed → Shipped → Verified

A card moves only on evidence: a git diff, a test or data check that ran after the last edit, a PR approval, a deploy, a clean monitoring window. What an agent says never moves a card.

Status

Phase 1 (the first usable slice) is built for Claude Code and git: hook capture into a local spool, a SQLite store, the git scanner, the linker, the stage machine (Asked, Built, Proven), a Stop hook gate in warn mode, a terminal status line, a secured local Track page, a one-process daemon, and the installer. It has not been used day to day for a week yet (the Phase 1 exit, see the roadmap), and there is no published release yet (the release pipeline is built, see RELEASING.md). Reviewed, Shipped and Verified need sources from later phases.

Tested in CI on Windows and Ubuntu. Developed and run by hand on Windows first.

Install

Recommended: let Claude Code do it. Open Claude Code in the repo you want to track and paste this:

Install Vantage for this repo. Follow https://github.com/ymatrix1/vantage/blob/main/docs/install-for-agents.md exactly: check the prerequisites, get Vantage if it is not already on this machine (from a release, or a checkout build), show me the dry run first and wait for my OK, then install, start it, verify with vantage doctor, and tell me what changed and how to undo it.

The agent follows the install guide and stops at anything that fails. You stay in control at two points:

1. Before anything changes, it shows you vantage add --dry-run: the exact files it would touch, nothing written. It waits for your explicit yes.
2. After the yes, it installs (with a backup of your Claude Code settings.json), starts the daemon, runs vantage doctor, and tells you how to open the Track page.

It never adds tokens or credentials, never commits anything, and never edits your settings by hand: only vantage add writes, and every entry it writes can be removed exactly (see Undo).

You need: Node.js 22.5 or newer (Vantage uses the built-in node:sqlite), git and Claude Code, plus pnpm if the agent has to build from a checkout. The agent checks these first and tells you what to install.

Releases. Once the first release is out, Vantage installs without a clone or a build: npm install -g @ymatrix1/vantage (or npx @ymatrix1/vantage --version) gives you the vantage command (vantage --version prints the version), and each GitHub Release carries the tarballs and a SHA256SUMS file. The agent tries the release first and falls back to a checkout. Until a release exists, the checkout path is the only one.

Then use Claude Code as usual. Open the Track page with vantage open (it opens http://127.0.0.1:<port> in your browser; --print only prints the URL). Items appear after the daemon's next pass, about 30 seconds.

git clone https://github.com/ymatrix1/vantage.git
cd vantage
pnpm install
pnpm build

alias vantage='node /path/to/vantage/packages/cli/dist/src/main.js'

After you install

Slash commands in Claude Code

Optional. Install the plugin (claude plugin install vantage@vantage, then a new session) to run the CLI from the chat:

Claude Code names plugin commands /<plugin>:<command>, so there is no plain /vantage open. Details in plugin/vantage.

What the installer changes

Nothing inside your repo changes.

What you will see

• Track page (vantage open): items grouped by attention, one row each with the six-dot track, proof state and flags. Click a row for its trace (why it is where it is).
• Status line (if installed): a short glyph line for the current session's item.
• Stop gate (warn mode): when an agent stops after editing code with no fresh test or data check, Claude Code shows a message naming the files and why. It never blocks. Set the mode with VANTAGE_GATE_MODE=off|warn or proof_gate = "off" in config.toml. Docs-only sessions never trigger it.

Measuring it

vantage stats prints numbers about the Track page from the local store, read-only (it works with the daemon running or stopped, and never writes):

vantage stats                 # summary, plus the last 14 days
vantage stats --days 7        # one row per day, for the week review
vantage stats --since 7d      # only items and events from the last 7 days (also 24h or YYYY-MM-DD)
vantage stats --repo myrepo   # one repo, matched by name; repeat the command per repo
vantage stats --json          # the same numbers as JSON

It reports items (total and active in 24 h, 7 d and 30 d), readable titles versus fallback rows (Session … or repo · branch · date), anchor kinds, session lineage (how many sessions sit on a real issue or branch item instead of a one-off Session row, sessions per item, sessions on a branch before and after the transcript-branch fix, derived sessions, sub-agent runs), Needs you (total and last 48 h, split by flag kind), stages, how many edited items reached Proven and how many Built items lost their proof, which checks ran (by runner family, plus one count for commands not recognised as checks), events by source and per day, database size and the age of the last stage pass. Each line says what it means, and a ✅, ⚠️ or ❌ shows where it stands against a goal (for example Needs you under 10). The goals are starting points, not product rules.

The output holds numbers and fixed labels only: no titles, commands, paths or repo names (the one echo is the --repo text you typed), so it is safe to paste into an issue. Days are UTC.

Classifying with Haiku

Optional and off by default. vantage classify asks your own Claude Code (claude -p, Haiku) to suggest titles, topics and groupings for items, so the Track page reads better. It runs in your Claude Code, so it uses your plan limits and Claude Code already sees this data. Status, stage and proof never come from the model: it only suggests text.

vantage classify --dry-run     # how many items, calls and bytes, and the exact message; calls nothing
vantage classify               # run in the background (needs the three switches below)
vantage classify accept        # preview, confirm, apply one batch (0.8 confidence and up)
vantage classify accept --all  # everything; also --kind titles|topics|groups and --repo NAME
vantage classify undo          # revert the last batch

Turn it on in ~/.vantage/config.toml:

[engines.classify]
enabled = true
[data_policy]
outside_calls = true
[data_policy.allow]
transcripts = true

Per item it sends only the repo name, branch, the first sentence of the first request (300 characters, URLs and secret-looking text removed), up to 10 file names (no paths), counts and the current title. Never commands, transcripts or paths. Nothing is applied until you confirm a preview; every batch has one undo; auto_accept is off unless you set it. Details: classify spec.

Where your data lives

All local, under ~/.vantage (or VANTAGE_HOME): spool/ (one line per hook event, including the tool input Claude Code passes to the hook), vantage.db (events, links, stages, proofs), token (the Track page token), status.json and health.json. Request titles are stored locally: the first sentence of a session's first request (cleaned of paths, URLs and anything that looks like a secret, at most 80 characters) becomes that session's item title and is kept in vantage.db, nowhere else. Turn it off with item_titles_from_requests = false in config.toml, see what is stored with vantage titles, and delete it with vantage titles clear. The daemon listens on 127.0.0.1 only, with a token and Host and Origin checks. Nothing leaves the machine, and no outside model is called. See privacy and the data policy.

Undo

vantage remove        # stop tracking this repo
vantage uninstall     # remove Vantage's hooks and status line from settings.json

Neither deletes ~/.vantage. Delete that folder yourself if you want the data gone.

If something is off

Developing

pnpm check                       # type check, lint, format, tests, fixture scrub
python tools/check_docs.py       # links, decision format and status, privacy scan
python -m unittest discover -s tools -p "test_*.py"

Packages: core (pure logic), daemon, hooks, hooks-native (Rust spool hook, built in CI), cli, ui. Read AGENTS.md first; tasks live in beans under .beans/.

Documents

The A2V plugin in plugin/a2v/ packages the method for any project: a communication rule, an output style, and the skills explain-top-down, prove-it, record-decision, handoff, land-the-day, answer-review, close-the-loop and plan-task. Install it with /plugin marketplace add ymatrix1/vantage, then /plugin install a2v@vantage.

Agent instructions: AGENTS.md (canonical), rules in .agents/rules/, skills in .agents/skills/. Tasks are tracked with beans in .beans/.