ait-vcs 1.1.1

Run Claude Code, Codex, Aider, Gemini CLI, and Cursor as isolated, reviewable attempts with repo-local memory, agent handoff, and apply/recover. MIT, no SaaS.

ait

ait is a local attempt ledger for AI coding agents.

It records every AI coding run so another agent can review, continue, or recover it later.

English · 繁體中文

You keep using Claude Code, Codex, Aider, Gemini CLI, Cursor CLI, or another agent the way you normally do. ait wraps that run, stores the prompt, diff, review, and decisions as a repo-local attempt under .ait/, then gives the next agent a usable handoff. You can ask a different agent to review the attempt before you apply it. Until you explicitly run ait apply, a wrapped agent's result stays out of the root checkout.

Package name: ait-vcs. Installed command: ait.

Why this exists

AI coding agents are good at making changes, but the surrounding workflow is still fragile:

• The next agent often starts from zero because the last agent's context lived in a closed chat.
• The agent that wrote the code is often the only one that "reviewed" it.
• Failed or interrupted runs can leave confusing working-copy debris.
• Useful decisions are hard to find after the run that produced them.

ait treats each run as an attempt: a proposal with provenance, review state, memory, and an explicit apply step.

Who needs it

ait is for engineers who already use AI coding agents on real repositories and want a local record of what happened. It is especially useful when you:

• Switch between Claude Code, Codex, Aider, Gemini CLI, Cursor CLI, or other agent CLIs.
• Want a second agent to review a risky change before it lands.
• Need to recover useful work from failed or interrupted runs.
• Want old prompts, decisions, and findings to be searchable from the repo.

30-second quickstart

Try the workflow without real API keys or an existing repo:

pipx install ait-vcs
ait demo

ait demo creates a temporary repo, runs a scripted multi-agent walkthrough, records attempts in a real local SQLite ledger, and shows a review gate blocking a risky change. Clean it up with:

ait demo --clean

Use it in a real repo:

cd your-repo
ait init
ait status --all # optional: confirm agent commands resolve through ait
claude ...        # codex / aider / gemini / cursor work the same way
ait status
ait apply latest

Requires Python 3.14+ and Git. If your default Python is older:

pipx install --python python3.14 ait-vcs

How it feels to use

1. Initialize a repo once with ait init.
2. Confirm the wrapper when you care: ait status claude-code or ait status --all.
3. Run your agent normally: claude ..., codex ..., aider ..., and so on.
4. ait records the run as an isolated attempt under .ait/.
5. Inspect it with ait status or ait attempt show <attempt-id>.
6. Optionally run a separate reviewer agent.
7. Apply, recover, resume, or discard the attempt.

The important behavior: the root checkout should not be changed by a wrapped run before ait apply. The agent's work is a proposal until you promote it.

Core concepts

Attempt

One agent run captured by ait: prompt, intent, exit status, changed files, diff, commits, traces, and review state.

ait attempt list
ait attempt show <attempt-id>

Repo-local ledger

.ait/ lives next to .git/. It is local metadata for this repository: no SaaS, no telemetry, no automatic sync. Nothing in .ait/ leaves your machine unless you copy, commit, export, or upload it yourself. The agent CLI you run still follows its own provider and network behavior.

Explicit apply

Wrapped agent runs land in an isolated workspace. ait apply latest is the moment you decide the attempt should affect the root checkout.

ait apply latest
ait recover latest
ait resume latest

Cross-agent handoff

The next wrapped agent can receive prior attempts, accepted facts, notes, and live repo memory files such as CLAUDE.md, AGENTS.md, .claude/memory.md, .codex/memory.md, and .cursor/rules.

Adversarial review

Use one agent to implement and another to challenge the result before apply. This does not prove the code is correct; it gives you a separate review pass with recorded findings.

ait review attempt latest-reviewable \
  --mode adversarial \
  --review-adapter claude-code

Memory recall

Search prior attempts and repo memory when a decision matters again:

ait memory recall "retry budget"

Common workflows

Record a normal agent run

ait init
claude -p "Refactor the auth retry logic"
ait status
ait attempt list
ait attempt show <attempt-id>

Review with a different agent

ait review attempt latest-reviewable \
  --mode adversarial \
  --review-adapter codex

ait review finding list --severity high

Continue after an interrupted or held run

ait recover latest
ait resume latest

Find an old decision

ait memory recall "why retry budget is three"
ait query --on attempt 'title~"retry"'

Compare multiple attempts

ait attempt list
ait attempt show <attempt-id>
ait graph --html

How this differs from Cursor, Aider, Claude Code, Codex, and Cline

ait is not another coding agent. It is the local workflow layer around the agents you already use.

Tool	Main job	What ait adds
Cursor / Cline	IDE-native agent experience.	A CLI-first attempt ledger that also works outside the editor and across multiple agent CLIs.
Claude Code / Codex / Gemini CLI	A coding agent that reads, edits, and runs commands.	Isolation, provenance, cross-agent handoff, review records, memory recall, and explicit apply/recover.
Aider	Pair-programming loop with model-driven edits and commits.	A repo-local attempt boundary around those edits, plus optional review by a different agent before apply.
Git worktrees alone	Isolated directories for parallel work.	Prompt and trace capture, attempt metadata, review findings, memory handoff, and daily commands for apply/recover.

The short version: your agent writes code; ait remembers what happened and keeps the result reviewable before it lands.

When not to use ait

Do not use ait if you need:

• An IDE plugin or autocomplete engine.
• A hosted dashboard, team sync service, or cross-machine ledger.
• A production-hardened system with a stable long-term storage contract.
• A guarantee that an AI reviewer catches every bug.
• A tool that replaces Claude Code, Codex, Aider, Cursor, Cline, or Git.

ait is most useful for engineers who already use agent CLIs and want local provenance, safer apply, cross-agent handoff, and a second-agent review pass.

Install

Recommended:

pipx install ait-vcs
ait --version

npm wrapper:

npm install -g ait-vcs
ait --version

Project virtual environment:

python3.14 -m venv .venv
.venv/bin/pip install ait-vcs
.venv/bin/ait --version

Pinned GitHub release:

pipx install "git+https://github.com/m24927605/ait.git@v1.1.1"

Upgrade:

ait upgrade
ait upgrade --dry-run

Requirements: Python 3.14+, Git, SQLite from the Python standard library. The npm package requires Node.js 18+ and installs the Python package behind the ait command.

Current status and limitations

ait is alpha software.

• Local-first: metadata lives under .ait/ in one repository on one machine.
• No telemetry, no SaaS dashboard, no automatic push, no automatic merge.
• Browser/HTML reporting is local; mutation still goes through CLI commands.
• Metadata export/import is currently a dry-run planning path, not sync.
• Adversarial review is an extra safety pass, not a correctness guarantee.
• Memory recall is useful, but you still decide which recalled context matters.

Docs and examples

• Documentation site
• Getting started
• Command reference
• Adversarial code review
• Pain-point demos
• Review benchmark dogfood report
• Examples
• CHANGELOG
• PyPI · npm

MIT licensed.