ait-vcs 0.55.29

Git worktree isolation and provenance for AI coding agents

ait

Git-native safety rails for AI coding agents

Run Claude Code, Codex, Aider, Gemini, and Cursor in isolated Git worktrees with traceable commits, reviewable attempts, and repo-local memory.

_{English · 繁體中文}

---

AI agents are fast. Git history, review discipline, and handoff context often are not.

ait wraps the agent CLIs you already use and turns each run into a reviewable attempt. The agent edits an isolated worktree, ait records what happened, and your main checkout stays untouched until you promote 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.

Why Developers Use ait

Problem with agent coding	What ait adds
A prompt edits many files at once	Each run happens in an isolated Git worktree
The diff has no useful provenance	Attempts link intent, command output, files, and commits
Agents leave partial or failed work behind	You can inspect, discard, rebase, or promote attempts
The next agent repeats old investigation	Repo-local memory summarizes prior attempts and commits
Tooling should stay local	Metadata lives in .ait/ inside your repository

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 attempt:

ait status
ait attempt show <attempt-id>

Promote only when you are ready:

ait attempt promote <attempt-id> --to main

Until promotion, your root checkout stays unchanged.

Core Features

Feature	Description
Worktree isolation	Agent edits happen away from your root checkout
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
Local memory	Prior attempts, commits, notes, and imported agent memory feed future runs
Review flow	Promote, discard, rebase, inspect, and query attempts using normal Git concepts

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/.

Run Claude Code in a Git worktree

ait adapter setup claude-code
claude -p --permission-mode bypassPermissions "Refactor the auth module"

ait captures the prompt, edited files, status, and resulting commits as one attempt. Promote it with ait attempt promote <id> --to main once you are happy with the diff.

Run Codex CLI safely on a real repository

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

Each Codex session edits an isolated worktree. Failed attempts are kept for inspection; only promoted attempts touch your root checkout.

Run Aider in an isolated worktree

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

Aider's commits land inside the attempt worktree, with full provenance linking the prompt, edited files, and commits.

Run Gemini CLI with attempt history

ait adapter setup gemini
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 adapter setup cursor
ait run --adapter cursor --intent "Migrate to new SDK" -- cursor

Cursor edits are confined to an attempt worktree. The attempt log keeps the changed files, exit status, and commits available for review and promotion.

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.

How It Works

your prompt
    |
    v
agent CLI wrapped by ait
    |
    v
isolated attempt worktree
    |
    v
attempt metadata + commits + memory
    |
    v
review, promote, discard, or rebase

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.29"

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.29 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

• Getting started
• Claude Code run worktree workflow
• Claude Code hook smoke test
• Long-term memory design
• Long-term memory acceptance
• Repo brain design
• Repo brain acceptance
• Release checklist