Structured episodic AI coding agent — an architect model plans, a builder model executes.
aimandshoot breaks large coding tasks into phased plans and executes them one turn at a time. The architect model decomposes your goal into a master plan with phases and tasks. The builder model executes each task, writing code, running tests, and reporting results. Defaults: Claude Opus/Sonnet on Anthropic, Gemini 3.1 Pro Preview/3.5 Flash on Google. You review every change before it's committed.
Per-turn prompt distillation keeps every prompt under 6K tokens regardless of project size. All state lives on the filesystem — sessions can be paused, resumed, and rolled back across process restarts.
- Two-model architecture — the architect plans, the builder executes. Automatic escalation to the architect when the builder fails repeatedly.
- Full-screen TUI — Live status dashboard, plan viewer, turn summaries, and approval menu powered by Textual.
- Human-in-the-loop approval — Review diffs, approve, reject with notes, pause, or force a replan before any change lands.
- Auto-pilot mode — Skip manual approval when tests pass (
--auto). - File rollback — Every file is snapshotted before edits. Roll back one turn or to any previous turn.
- Budget enforcement — Set a USD spend limit per session. Alerts at configurable thresholds, hard stop at the limit.
- Prompt caching — Three-block cache split (stable / per-phase / per-turn) reduces token costs on Anthropic.
- Sandbox mode — Dry-run all file operations and bash commands without touching disk.
- Retry logic — Failed tasks retry up to N times with failure context, then auto-escalate to the architect.
- Existing project support — Scan an existing codebase and plan additions/changes on top of it.
- Audit trail — Every model call, file write, and human decision is logged to
audit.jsonl.
aimandshoot is a CLI tool — install it with pipx (or
uv tool). This gives it its own isolated
environment: its dependencies resolve cleanly against nothing, never touch your projects,
and only the aimandshoot command lands on your PATH.
# From GitHub (PyPI release planned — will become `pipx install aimandshoot`):
pipx install git+https://github.com/christiano-developer/aimandshoot.git
# Or with uv:
uv tool install git+https://github.com/christiano-developer/aimandshoot.git
# With Vertex AI support:
pipx install "aimandshoot[vertex] @ git+https://github.com/christiano-developer/aimandshoot.git"To upgrade or remove:
pipx upgrade aimandshoot
pipx uninstall aimandshootInstalling with plain
pipinto a virtualenv also works (see Development), but pipx is the recommended path for end users.
Configuration is per project: credentials live in a .env.aas file in the
project root (auto-added to that project's .gitignore), and model choices in
config.yaml next to it.
# Interactive setup — run inside your project; asks provider, API key, and
# which models to use, then writes ./.env.aas + ./config.yaml
aimandshoot configureRunning bare aimandshoot in a project with no credentials triggers the same
setup inline. Or manually create a .env.aas file
(see .env.aas.example):
# Anthropic direct
PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
# Google Vertex AI
PROVIDER=vertex
VERTEX_PROJECT_ID=your-gcp-project-id
VERTEX_REGION=us-east5
# Google Gemini direct (requires the [gemini] extra)
PROVIDER=google
GEMINI_API_KEY=...
# Mock mode (for development/testing)
PROVIDER=mock
MOCK_MODE=realistic# Interactive wizard (recommended for first use)
aimandshoot
# Initialise a new project
aimandshoot init --goal "Build a FastAPI todo app with SQLite"
# Initialise with a specific tech stack
aimandshoot init --goal "Build a REST API" --stack "Python/FastAPI/pytest"
# Start the agent (launches full-screen TUI)
aimandshoot start
# Start with auto-approval (approve if tests pass)
aimandshoot start --auto
# Start in sandbox mode (no file writes)
aimandshoot start --sandbox
# Check session status
aimandshoot status
# Roll back the last turn
aimandshoot rollback
# Roll back to a specific turn
aimandshoot rollback --to 3
# View completed turns
aimandshoot history
# View cost breakdown
aimandshoot cost
# Query audit log
aimandshoot audit
aimandshoot audit --turn 5 --event token_usage --limit 10
# Pause / resume
aimandshoot pause
aimandshoot resume
# Force an architect replan
aimandshoot replanThe TUI is a two-pane workspace: a scrollable session transcript with an always-active prompt box on the left, session state and config on the right. Type plain text + Enter in the prompt box to save a steering note for the next turn; PgUp/PgDn or the mouse wheel scroll the transcript.
Single keys act when the prompt box is empty and a decision is pending:
| Key | Action |
|---|---|
a |
Approve the current turn |
r |
Reject — the box switches to rejection-note mode |
d |
View this turn's file diffs (pager) |
t |
View test output (pager) |
e |
Open changed files in $EDITOR (TUI suspends) |
p |
Pause the session |
o |
Force an architect replan (with confirmation) |
? |
Help overlay (available any time) |
| Command | Description |
|---|---|
/do <task> |
Inject a specific task for the next turn |
/plan <note> |
Send a planning note to the architect |
/skip |
Skip the current task |
/rollback |
Rollback the last turn (with confirmation) |
/pause |
Pause the session |
/help |
Show available commands |
# Models
architect_model: claude-opus-4-6
builder_model: claude-sonnet-4-6
# Budget (USD)
budget_limit: 10.00
alert_threshold: 7.00
# Approval
approval_mode: manual # manual | auto
opus_always_manual: true # architect plan updates always require manual approval
# Effort — low | medium | high (high adds extended thinking).
# Context depth — recent completed-turn records sent with each prompt.
# Both are live-tunable from the TUI (/effort, /context).
effort: medium
context_depth: 1
# Token limits — uncomment to override the effort preset's output cap
# max_output_tokens: 4096
# Test runner
test_command: "python -m pytest tests/ -x -q"
test_required: false # false = warn but don't block on test failure
# File safety
whitelist: [] # empty = allow all paths (add dirs to restrict)
max_file_bytes: 1000000 # 1MB — writes above this require confirmation
max_retries: 3 # escalate to the architect after this many failures
# Dashboard
dashboard_enabled: trueaimandshoot has built-in guards to prevent dangerous file operations:
- NEVER_WRITE patterns:
.env,.pem,.key,.p12,.pfx,.secret,id_rsa, etc. are unconditionally blocked from writes. - Blacklist:
plans/and.aimandshoot/directories are read-only for the agent. - Whitelist: Optionally restrict which directories the agent can write to.
- Protected paths: Directories you mark as protected during init are never read or written.
- Size limit: Files over 1MB require explicit confirmation.
- Snapshots: Every file is backed up before modification for rollback.
User ─── CLI/Wizard ─── Orchestrator ─┬── Router ──── Anthropic / Vertex / Mock
├── Assembler ── Plan Store (filesystem)
├── Parser ───── XML response extraction
├── Tools ────── write_file, str_replace, read_file, run_bash, list_files
├── Approvals ── TUI / terminal approval gate
├── Audit ────── Cost tracking, budget enforcement
├── Snapshots ── Per-turn file rollback
├── Tests ────── Auto-test after file writes
└── Dashboard ── Textual TUI status panels
- Init: the architect decomposes your goal into a master plan with phased subplans.
- Turn loop: Each turn, the assembler builds a prompt from the current plan state (kept under 6K tokens). Sonnet executes the current task and returns structured XML with file operations and plan updates.
- Apply: File writes and edits are extracted from the response and applied via the tools system (with snapshots for rollback).
- Test: If files were written, the test suite runs automatically.
- Approve: You review the diff, test results, and decide: approve, reject, pause, or replan.
- Advance: On approval, the plan updates are applied and the next task begins.
- Escalate: If Sonnet fails repeatedly (default 3 retries), Opus is called to replan.
All state is stored on the filesystem under the project root:
plans/ # Plan files (Opus writes)
├── master_plan.md # Top-level goal, phases, constraints
├── current_task.md # Active task definition
├── completed.md # Append-only log of completed turns
├── human_note.md # Human steering note
└── subplans/phase*.md # Per-phase task lists
outcomes/ # Turn outcomes and snapshots
├── turn_NNNN.md # Per-turn outcome records
└── snapshots/turn_NNNN/ # Pre-edit file backups
.aimandshoot/ # Session metadata
├── session.json # Turn counter, costs, retry state
└── audit.jsonl # Append-only event log
# Clone and install in dev mode (editable, inside a venv — not pipx)
git clone https://github.com/christiano-developer/aimandshoot.git
cd aimandshoot
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Run with mock provider (no API key needed)
PROVIDER=mock MOCK_MODE=realistic aimandshoot
# Run tests (when available)
python -m pytest tests/ -x -q| Package | Purpose |
|---|---|
anthropic>=0.40.0 |
Claude API client |
rich>=13.0 |
Terminal formatting |
pyyaml>=6.0 |
Config file parsing |
python-dotenv>=1.0 |
Environment variable loading |
textual>=0.60.0 |
Full-screen TUI framework |
google-auth>=2.0 |
Google Cloud auth (should be optional) |
questionary>=2.0 |
Interactive prompts for CLI wizard |
- No Windows support — Terminal key reading uses
termios(Unix-only). - No structured logging — Uses
print()for all output. Production deployments should add proper logging. - Session file safety —
session.jsonreads/writes are not atomic or locked. Avoid running multiple instances on the same project. - Parallel workers not integrated —
workers.pyinfrastructure exists but is not wired into the orchestrator. - No unit tests — The project needs its own test suite for CI/production readiness.
MIT