ait-vcs 0.55.49

Git worktree isolation and provenance for AI coding agents — wraps Claude Code, Codex, Aider, Gemini CLI, Cursor. MIT, Python, no SaaS.

ait

Git-native version control layer for AI coding agents

Claude Code · Codex CLI · Aider · Gemini CLI · Cursor

_{English · 繁體中文}

---

ait is a Git-native version control layer for AI coding agents (Claude Code, Codex CLI, Aider, Gemini CLI, Cursor) — adding worktree isolation, attempt provenance, cross-agent memory, and reviewable apply/recover flow on top of Git. Open source (MIT), Python 3.14+, dependency-free, no SaaS, no telemetry.

AI agents are fast. Git history, review discipline, and handoff context often are not. ait closes that gap as a thin layer on top of Git — it is not an agent and not a Git replacement. It wraps the agent CLIs you already use and turns each run into a reviewable attempt: the agent edits in an internal isolated environment, ait records what happened, and your main checkout stays untouched until you apply the result.

pipx install ait-vcs
cd your-repo
ait init
direnv allow   # only if prompted

claude ...

Prefer npm?

npm install -g ait-vcs
cd your-repo
ait init
claude ...

The package is named ait-vcs on PyPI and npm. The installed command is ait.

Problems ait Solves

Problem with agent coding today	What ait adds
A bad prompt rewrites half your repo before you notice	Each run lands in an isolated Git worktree — your root checkout never moves
The diff has no useful provenance — which prompt produced it?	Attempts link intent, command output, files, and commits in one record
Failed or partial runs leave your working copy half-broken	Bad attempts stay recoverable; ait recover latest shows what AIT kept
The next agent repeats investigation you already paid tokens for	Repo-local memory feeds prior attempts and commits to the next run
Two agents on the same task stomp each other	Each attempt has its own worktree — run N agents in parallel
Did the agent really fix it, or just claim it did?	Explicit ait apply latest keeps speculative changes out of main until you decide
Cross-agent hand-offs lose every previous decision	Memory layer auto-imports CLAUDE.md, AGENTS.md, and prior attempts
Provenance tooling wants to ship your code to a SaaS	Metadata stays in .ait/ next to .git/ — harness daemon is local-only (Unix socket, no network), no telemetry
"Where's that prompt I wrote last month?" → grep shell history	Query attempts, intents, and commits with a structured DSL

ait is not another agent. It is the Git layer around the agents you already trust.

What It Feels Like

Initialize once:

ait init
direnv allow   # only if prompted

Then keep using your agent:

claude ...
codex ...
aider ...
gemini ...
cursor ...

After a successful wrapped run, inspect the result:

ait status
ait recover latest --debug   # optional low-level details

Apply only when you are ready:

ait apply latest

Until apply, your root checkout stays unchanged. If apply is unsafe because your local edits overlap with the result, AIT holds the result for recovery instead of stashing or overwriting your work.

Inspect cleanup candidates before reclaiming old internal workspaces:

ait cleanup
ait cleanup --apply

ait cleanup defaults to a dry run. Apply mode removes safe terminal workspaces such as applied or discarded attempts while retaining active, pending, and reviewable attempts by default.

Core Features

Feature	Description
Worktree isolation	Agent edits happen away from your root checkout; worktrees are an internal detail
Attempt provenance	Commands, status, output, changed files, and commits stay linked
Agent wrappers	Repo-local claude, codex, aider, gemini, and cursor wrappers
Auto commit capture	Successful changes become attempt-linked commits, without duplicating existing commits
Cleanup dry-run	Inspect and reclaim safe terminal attempt workspaces without touching reviewable work
Local memory	Prior attempts, commits, notes, and imported agent memory feed future runs
Review flow	Apply, recover, inspect, and query attempts without managing worktrees by hand

Quick Examples

Set explicit intent and commit text:

AIT_INTENT="Update README" \
AIT_COMMIT_MESSAGE="update README with Claude" \
claude -p --permission-mode bypassPermissions \
  "Shorten the README and improve the quickstart"

Wrap a command directly:

ait run --adapter claude-code --intent "Refactor query parser" -- claude
ait run --adapter codex --intent "Implement parser edge cases" -- codex
ait run --adapter aider --intent "Fix auth expiry" -- aider src/auth.py
ait run --adapter shell --intent "Regenerate fixtures" -- \
  python scripts/regenerate_fixtures.py

Use repo-local memory:

ait memory
ait memory search "auth adapter"
ait memory recall "billing retry"

Repair local setup if wrappers drift:

ait repair
ait repair codex

Integrations

ait ships first-class adapters for the agents most teams already run. Each adapter wraps the upstream CLI, isolates its work in a Git worktree, and records the attempt locally in .ait/.

ait init detects every supported agent CLI on $PATH and wires it up automatically — wrappers under .ait/bin/, hooks merged into the relevant .claude/, .codex/, .gemini/ config. The per-adapter sections below assume you already ran ait init. To re-run setup explicitly (e.g. after upgrading an agent), use ait adapter setup <name>.

Run Claude Code safely

claude -p --permission-mode bypassPermissions "Refactor the auth module"

ait captures the prompt, edited files, status, and resulting commits as one attempt. Apply it with ait apply latest once you are happy with the result, or use ait run --apply auto ... when you want safe results applied immediately.

Run Codex CLI safely on a real repository

ait run --adapter codex --intent "Implement parser edge cases" -- codex

Each Codex session edits in isolation. Failed attempts are kept for recovery; only applied attempts touch your root checkout.

Run Aider in isolation

ait run --adapter aider --intent "Fix auth expiry" -- aider src/auth.py

Aider's commits are captured as attempt results, with full provenance linking the prompt, edited files, and commits.

Run Gemini CLI with attempt history

ait run --adapter gemini --intent "Add config validation" -- gemini

Gemini sessions are recorded as attempts the same way as Claude Code and Codex. ait memory recall later surfaces what each agent tried.

Run Cursor agents with reviewable provenance

ait run --adapter cursor --intent "Migrate to new SDK" -- cursor

Cursor edits are confined until you apply them. The attempt log keeps the changed files, exit status, and commits available for review and recovery.

Wrap any other shell agent

ait run --adapter shell --intent "Regenerate fixtures" -- \
  python scripts/regenerate_fixtures.py

Use the generic shell adapter to give attempt provenance to any custom agent or script.

Compared to alternatives

ait is the layer around the agents, not a replacement.

You already use	ait adds
Naked git worktree + manual cleanup	Auto-managed internal workspaces, attempt records, apply/recover verbs, queryable history — see ait vs naked git-worktree
Aider's --auto-commits	Outer-layer attempt history (Aider commits land inside an ait attempt), cross-session memory, multi-agent handoff
Claude Code's built-in worktrees	Cross-agent (not Claude-only), structured attempt records, query DSL, explicit apply/recover
SaaS observability (Langfuse, Braintrust)	Local-first, no telemetry, git-native (commit-linked, not token-linked); they operate at the LLM-call layer, ait at the git-call layer — both stack

How It Works

your prompt
    |
    v
agent CLI wrapped by ait
    |
    v
internal isolated workspace
    |
    v
attempt metadata + commits + memory
    |
    v
review, apply, recover, or inspect

The wrapped process receives:

AIT_INTENT_ID
AIT_ATTEMPT_ID
AIT_WORKSPACE_REF
AIT_CONTEXT_FILE   # when context is enabled

AIT_CONTEXT_FILE contains a compact repo-local handoff selected from previous attempts, commits, curated notes, and imported agent memory files such as CLAUDE.md and AGENTS.md.

Install

Recommended:

pipx install ait-vcs
ait --version

Virtual environment:

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

npm wrapper:

npm install -g ait-vcs
ait --version

Tagged GitHub release:

pipx install "git+https://github.com/m24927605/ait.git@v0.55.49"

Upgrade:

ait upgrade
ait --version

Preview an upgrade:

ait upgrade --dry-run

Useful Commands

ait status
ait status --all
ait doctor
ait doctor --fix

ait adapter list
ait adapter doctor claude-code
ait adapter setup claude-code

ait attempt list
ait attempt show <attempt-id>
ait intent show <intent-id>
ait context <intent-id>

ait memory
ait memory search "auth adapter"
ait memory lint
ait memory lint --fix

ait graph
ait graph --html

Shell auto-activation:

ait shell show --shell zsh
ait shell install --shell zsh
ait shell uninstall --shell zsh

Requirements

• Python 3.14+
• Git
• SQLite from the Python standard library
• Node.js 18+ only when installing through npm

Status

ait is currently 0.55.49 and alpha quality. It is intended for local dogfooding and early users who are comfortable with Git workflows.

Metadata is local to one repository under .ait/. It is not synchronized across machines.

Development

Set up the repository:

python3.14 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/pip install pytest

Verify:

.venv/bin/pytest -q
.venv/bin/ait --version
.venv/bin/ait --help

Before a release:

git status --short
.venv/bin/pytest -q

The release version in pyproject.toml, the Git tag, and this README should match.

Documentation

• Documentation site — full docs in English and 繁體中文
• Why ait — the ten problems ait solves
• Getting started
• AI search facts (Q&A)
• Compare: naked git-worktree vs ait
• Command reference
• SEO strategy (internal)

For internal design notes (specs, memory architecture, refactor plans), see docs/.