{"id":49299762,"url":"https://github.com/m24927605/ait","last_synced_at":"2026-05-25T19:01:31.284Z","repository":{"id":353894354,"uuid":"1221346894","full_name":"m24927605/ait","owner":"m24927605","description":"AI coding agents should work in attempts, not your working tree","archived":false,"fork":false,"pushed_at":"2026-05-23T05:19:13.000Z","size":5327,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T06:25:34.815Z","etag":null,"topics":["agent-harness","agent-isolation","agentic","ai-agents","ai-coding","ai-tools","aider","claude-code","code-provenance","codex","coding-assistant","cursor","developer-tools","gemini-cli","git","git-worktree","llm-agents","python","vcs","worktree"],"latest_commit_sha":null,"homepage":"https://m24927605.github.io/ait/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m24927605.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T04:35:47.000Z","updated_at":"2026-05-23T05:19:16.000Z","dependencies_parsed_at":"2026-05-02T12:01:09.319Z","dependency_job_id":null,"html_url":"https://github.com/m24927605/ait","commit_stats":null,"previous_names":["m24927605/ait"],"tags_count":133,"template":false,"template_full_name":null,"purl":"pkg:github/m24927605/ait","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m24927605%2Fait","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m24927605%2Fait/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m24927605%2Fait/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m24927605%2Fait/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m24927605","download_url":"https://codeload.github.com/m24927605/ait/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m24927605%2Fait/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33387757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-harness","agent-isolation","agentic","ai-agents","ai-coding","ai-tools","aider","claude-code","code-provenance","codex","coding-assistant","cursor","developer-tools","gemini-cli","git","git-worktree","llm-agents","python","vcs","worktree"],"created_at":"2026-04-26T06:04:34.487Z","updated_at":"2026-05-25T19:01:31.276Z","avatar_url":"https://github.com/m24927605.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ait\n\n**ait is a local attempt ledger for AI coding agents.**\n\nIt records every AI coding run so another agent can review, continue, or\nrecover it later.\n\n\u003cp\u003e\n  \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e ·\n  \u003ca href=\"README.zh-TW.md\"\u003e繁體中文\u003c/a\u003e\n\u003c/p\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/ait-vcs?label=PyPI)](https://pypi.org/project/ait-vcs/)\n[![npm](https://img.shields.io/npm/v/ait-vcs?label=npm)](https://www.npmjs.com/package/ait-vcs)\n[![Python](https://img.shields.io/badge/python-3.14%2B-blue)](pyproject.toml)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\nYou keep using Claude Code, Codex, Aider, Gemini CLI, Cursor CLI, or another\nagent the way you normally do. `ait` wraps that run, stores the prompt, diff,\nreview, and decisions as a repo-local attempt under `.ait/`, then gives the\nnext agent a usable handoff. You can ask a different agent to review the\nattempt before you apply it. Until you explicitly run `ait apply`, a wrapped\nagent's result stays out of the root checkout.\n\nPackage name: `ait-vcs`. Installed command: `ait`.\n\n## Why this exists\n\nAI coding agents are good at making changes, but the surrounding workflow is\nstill fragile:\n\n- The next agent often starts from zero because the last agent's context lived\n  in a closed chat.\n- The agent that wrote the code is often the only one that \"reviewed\" it.\n- Failed or interrupted runs can leave confusing working-copy debris.\n- Useful decisions are hard to find after the run that produced them.\n\n`ait` treats each run as an attempt: a proposal with provenance, review state,\nmemory, and an explicit apply step.\n\n## Who needs it\n\n`ait` is for engineers who already use AI coding agents on real repositories\nand want a local record of what happened. It is especially useful when you:\n\n- Switch between Claude Code, Codex, Aider, Gemini CLI, Cursor CLI, or other\n  agent CLIs.\n- Want a second agent to review a risky change before it lands.\n- Need to recover useful work from failed or interrupted runs.\n- Want old prompts, decisions, and findings to be searchable from the repo.\n\n## 30-second quickstart\n\nTry the workflow without real API keys or an existing repo:\n\n```bash\npipx install ait-vcs\nait demo\n```\n\n`ait demo` creates a temporary repo, runs a scripted multi-agent walkthrough,\nrecords attempts in a real local SQLite ledger, and shows a review gate blocking\na risky change. Clean it up with:\n\n```bash\nait demo --clean\n```\n\nUse it in a real repo:\n\n```bash\ncd your-repo\nait init\nait status --all # optional: confirm agent commands resolve through ait\nclaude ...        # codex / aider / gemini / cursor work the same way\nait status\nait apply latest\n```\n\nRequires Python 3.14+ and Git. If your default Python is older:\n\n```bash\npipx install --python python3.14 ait-vcs\n```\n\n## How it feels to use\n\n1. Initialize a repo once with `ait init`.\n2. Confirm the wrapper when you care: `ait status claude-code` or\n   `ait status --all`.\n3. Run your agent normally: `claude ...`, `codex ...`, `aider ...`, and so on.\n4. `ait` records the run as an isolated attempt under `.ait/`.\n5. Inspect it with `ait status` or `ait attempt show \u003cattempt-id\u003e`.\n6. Optionally run a separate reviewer agent.\n7. Apply, recover, resume, or discard the attempt.\n\nThe important behavior: the root checkout should not be changed by a wrapped\nrun before `ait apply`. The agent's work is a proposal until you promote it.\n\n## Core concepts\n\n**Attempt**\n\nOne agent run captured by `ait`: prompt, intent, exit status, changed files,\ndiff, commits, traces, and review state.\n\n```bash\nait attempt list\nait attempt show \u003cattempt-id\u003e\n```\n\n**Repo-local ledger**\n\n`.ait/` lives next to `.git/`. It is local metadata for this repository: no\nSaaS, no telemetry, no automatic sync. Nothing in `.ait/` leaves your machine\nunless you copy, commit, export, or upload it yourself. The agent CLI you run\nstill follows its own provider and network behavior.\n\n**Explicit apply**\n\nWrapped agent runs land in an isolated workspace. `ait apply latest` is the\nmoment you decide the attempt should affect the root checkout.\n\n```bash\nait apply latest\nait recover latest\nait resume latest\n```\n\n**Cross-agent handoff**\n\nThe next wrapped agent can receive prior attempts, accepted facts, notes, and\nlive repo memory files such as `CLAUDE.md`, `AGENTS.md`, `.claude/memory.md`,\n`.codex/memory.md`, and `.cursor/rules`.\n\n**Adversarial review**\n\nUse one agent to implement and another to challenge the result before apply.\nThis does not prove the code is correct; it gives you a separate review pass\nwith recorded findings.\n\n```bash\nait review attempt latest-reviewable \\\n  --mode adversarial \\\n  --review-adapter claude-code\n```\n\n**Memory recall**\n\nSearch prior attempts and repo memory when a decision matters again:\n\n```bash\nait memory recall \"retry budget\"\n```\n\n## Common workflows\n\n**Record a normal agent run**\n\n```bash\nait init\nclaude -p \"Refactor the auth retry logic\"\nait status\nait attempt list\nait attempt show \u003cattempt-id\u003e\n```\n\n**Review with a different agent**\n\n```bash\nait review attempt latest-reviewable \\\n  --mode adversarial \\\n  --review-adapter codex\n\nait review finding list --severity high\n```\n\n**Continue after an interrupted or held run**\n\n```bash\nait recover latest\nait resume latest\n```\n\n**Find an old decision**\n\n```bash\nait memory recall \"why retry budget is three\"\nait query --on attempt 'title~\"retry\"'\n```\n\n**Compare multiple attempts**\n\n```bash\nait attempt list\nait attempt show \u003cattempt-id\u003e\nait graph --html\n```\n\n## How this differs from Cursor, Aider, Claude Code, Codex, and Cline\n\n`ait` is not another coding agent. It is the local workflow layer around the\nagents you already use.\n\n| Tool | Main job | What `ait` adds |\n| --- | --- | --- |\n| Cursor / Cline | IDE-native agent experience. | A CLI-first attempt ledger that also works outside the editor and across multiple agent CLIs. |\n| 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. |\n| 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. |\n| Git worktrees alone | Isolated directories for parallel work. | Prompt and trace capture, attempt metadata, review findings, memory handoff, and daily commands for apply/recover. |\n\nThe short version: your agent writes code; `ait` remembers what happened and\nkeeps the result reviewable before it lands.\n\n## When not to use ait\n\nDo not use `ait` if you need:\n\n- An IDE plugin or autocomplete engine.\n- A hosted dashboard, team sync service, or cross-machine ledger.\n- A production-hardened system with a stable long-term storage contract.\n- A guarantee that an AI reviewer catches every bug.\n- A tool that replaces Claude Code, Codex, Aider, Cursor, Cline, or Git.\n\n`ait` is most useful for engineers who already use agent CLIs and want local\nprovenance, safer apply, cross-agent handoff, and a second-agent review pass.\n\n## Install\n\nRecommended:\n\n```bash\npipx install ait-vcs\nait --version\n```\n\nnpm wrapper:\n\n```bash\nnpm install -g ait-vcs\nait --version\n```\n\nProject virtual environment:\n\n```bash\npython3.14 -m venv .venv\n.venv/bin/pip install ait-vcs\n.venv/bin/ait --version\n```\n\nPinned GitHub release:\n\n```bash\npipx install \"git+https://github.com/m24927605/ait.git@v1.2.0\"\n```\n\nUpgrade:\n\n```bash\nait upgrade\nait upgrade --dry-run\n```\n\nRequirements: Python 3.14+, Git, SQLite from the Python standard library.\nThe npm package requires Node.js 18+ and installs the Python package behind the\n`ait` command.\n\n## Current status and limitations\n\n`ait` is alpha software.\n\n- Local-first: metadata lives under `.ait/` in one repository on one machine.\n- No telemetry, no SaaS dashboard, no automatic push, no automatic merge.\n- Browser/HTML reporting is local; mutation still goes through CLI commands.\n- Metadata export/import is currently a dry-run planning path, not sync.\n- Adversarial review is an extra safety pass, not a correctness guarantee.\n- Memory recall is useful, but you still decide which recalled context matters.\n\n## Docs and examples\n\n- [Documentation site](https://m24927605.github.io/ait/)\n- [Getting started](https://m24927605.github.io/ait/getting-started/)\n- [Command reference](https://m24927605.github.io/ait/reference/commands/)\n- [Adversarial code review](https://m24927605.github.io/ait/reference/adversarial-code-review/)\n- [Pain-point demos](https://m24927605.github.io/ait/demos/pain-point-demos/)\n- [Review benchmark dogfood report](docs/review-benchmark-dogfood-report.md)\n- [Examples](examples/)\n- [CHANGELOG](CHANGELOG.md)\n- [PyPI](https://pypi.org/project/ait-vcs/) · [npm](https://www.npmjs.com/package/ait-vcs)\n\nMIT licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm24927605%2Fait","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm24927605%2Fait","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm24927605%2Fait/lists"}