A production-ready framework for autonomous multi-session AI coding. Build complete applications or add features to existing projects through coordinated AI agent sessions.

What It Does

Auto Claude uses a multi-agent pattern to build software autonomously:

Spec Creation Pipeline (8 phases)

Discovery - Analyzes project structure
Requirements Gatherer - Collects user requirements interactively
Research Agent - Validates external integrations against documentation
Context Discovery - Finds relevant files in codebase
Spec Writer - Creates comprehensive spec.md
Spec Critic - Uses ultrathink to find and fix issues before implementation
Planner - Creates chunk-based implementation plan
Validation - Ensures all outputs are valid

Implementation Pipeline

Planner Agent (Session 1) - Analyzes spec, creates chunk-based implementation plan
Coder Agent (Sessions 2+) - Implements chunks one-by-one with verification
QA Reviewer Agent - Validates all acceptance criteria before sign-off
QA Fixer Agent - Fixes issues found by QA in a self-validating loop

Each session runs with a fresh context window. Progress is tracked via implementation_plan.json and Git commits.

Quick Start

Prerequisites

Python 3.8+
Claude Code CLI (npm install -g @anthropic-ai/claude-code)

Setup

Step 1: Copy the auto-claude folder into your project

# Copy the auto-claude folder to your project root
cp -r auto-claude /path/to/your/project/

Step 2: Set up Python environment

cd your-project
cd auto-claude

# Using uv (recommended)
uv venv && uv pip install -r requirements.txt

# Or using standard Python
python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

Step 3: Configure environment

cp .env.example .env

# Get your OAuth token
claude setup-token

# Add the token to .env
# CLAUDE_CODE_OAUTH_TOKEN=your-token-here

Step 4: Create a spec using the orchestrator

# Activate the virtual environment
source auto-claude/.venv/bin/activate

# Create a spec interactively
python auto-claude/spec_runner.py --interactive

# Or with a task description
python auto-claude/spec_runner.py --task "Add user authentication with OAuth"

The spec orchestrator will:

Analyze your project structure
Gather requirements interactively
Research external integrations against documentation
Discover relevant codebase context
Write the specification
Self-critique using ultrathink to find and fix issues
Generate an implementation plan
Validate all outputs

Step 5: Run the autonomous build

python auto-claude/run.py --spec 001

Managing Specs

# List all specs and their status
python auto-claude/run.py --list

# Run a specific spec
python auto-claude/run.py --spec 001
python auto-claude/run.py --spec 001-feature-name

# Run with parallel workers (2-3x speedup for independent phases)
python auto-claude/run.py --spec 001 --parallel 2
python auto-claude/run.py --spec 001 --parallel 3

# Limit iterations for testing
python auto-claude/run.py --spec 001 --max-iterations 5

QA Validation

After all chunks are complete, QA validation runs automatically:

# QA runs automatically after build completes
# To skip automatic QA:
python auto-claude/run.py --spec 001 --skip-qa

# Run QA validation manually on a completed build
python auto-claude/run.py --spec 001 --qa

# Check QA status
python auto-claude/run.py --spec 001 --qa-status

The QA validation loop:

QA Reviewer checks all acceptance criteria (unit tests, integration tests, E2E, browser verification, database migrations)
If issues found → creates QA_FIX_REQUEST.md
QA Fixer applies fixes
Loop repeats until approved (up to 50 iterations)
Final sign-off recorded in implementation_plan.json

Spec Creation Pipeline (Dynamic Complexity)

The spec_runner.py orchestrator automatically assesses task complexity and adapts the number of phases accordingly:

# Simple task (auto-detected) - runs 3 phases
python auto-claude/spec_runner.py --task "Fix button color in Header"

# Complex task (auto-detected) - runs 8 phases
python auto-claude/spec_runner.py --task "Add Graphiti memory integration with FalkorDB"

# Force a specific complexity level
python auto-claude/spec_runner.py --task "Update text" --complexity simple

# Interactive mode
python auto-claude/spec_runner.py --interactive

# Continue an interrupted spec
python auto-claude/spec_runner.py --continue 001-feature

Complexity Tiers:

Tier	Phases	When Used
SIMPLE	3	1-2 files, single service, no integrations (UI fixes, text changes)
STANDARD	6	3-10 files, 1-2 services, minimal integrations (features, bug fixes)
COMPLEX	8	10+ files, multiple services, external integrations (integrations, migrations)

Phase Matrix:

Phase	Simple	Standard	Complex
Discovery	✓	✓	✓
Requirements	-	✓	✓
Research	-	-	✓
Context	-	✓	✓
Spec Writing	Quick	Full	Full
Self-Critique	-	-	✓
Planning	Auto	✓	✓
Validation	✓	✓	✓

Complexity Detection Signals:

Keywords: "fix", "typo", "color" → Simple | "integrate", "migrate", "oauth" → Complex
External integrations detected (redis, postgres, graphiti, etc.)
Number of files/services mentioned
Infrastructure changes (docker, deploy, schema)

Manual validation:

python auto-claude/validate_spec.py --spec-dir auto-claude/specs/001-feature --checkpoint all

Isolated Worktrees (Safe by Default)

Auto Claude uses Git worktrees to keep your work completely safe. All AI-generated code is built in a separate workspace (.worktrees/auto-claude/) - your current files are never touched until you explicitly merge.

How it works:

When you run auto-claude, it creates an isolated workspace
All coding happens in .worktrees/auto-claude/ on its own branch
You can cd into the worktree to test the feature before accepting
Only when you're satisfied, merge the changes into your project

After a build completes, you can:

# Test the feature in the isolated workspace
cd .worktrees/auto-claude/
npm run dev  # or your project's run command

# See what was changed
python auto-claude/run.py --spec 001 --review

# Add changes to your project
python auto-claude/run.py --spec 001 --merge

# Discard if you don't like it (requires confirmation)
python auto-claude/run.py --spec 001 --discard

Key benefits:

Safety: Your uncommitted work is protected - auto-claude won't touch it
Testability: Run and test the feature before committing to it
Easy rollback: Don't like it? Just discard the worktree
Parallel-safe: Multiple workers can build without conflicts

If you have uncommitted changes, auto-claude automatically uses isolated mode. With a clean working directory, you can choose between isolated (recommended) or direct mode.

Interactive Controls

While the agent is running, you can:

# Pause and optionally add instructions
Ctrl+C (once)
# You'll be prompted to add instructions for the agent
# The agent will read these instructions when you resume

# Exit immediately without prompting
Ctrl+C (twice)
# Press Ctrl+C again during the prompt to exit

Alternative (file-based):

# Create PAUSE file to pause after current session
touch auto-claude/specs/001-name/PAUSE

# Manually edit instructions file
echo "Focus on fixing the login bug first" > auto-claude/specs/001-name/HUMAN_INPUT.md

Project Structure

your-project/
├── .worktrees/              # Created during build (git-ignored)
│   └── auto-claude/          # Isolated workspace for AI coding
├── auto-claude/
│   ├── run.py               # Build entry point
│   ├── spec_runner.py       # Spec creation orchestrator (8-phase pipeline)
│   ├── validate_spec.py     # Spec validation with JSON schemas
│   ├── agent.py             # Session orchestration
│   ├── planner.py           # Deterministic implementation planner
│   ├── worktree.py          # Git worktree management
│   ├── workspace.py         # Workspace selection UI
│   ├── coordinator.py       # Parallel execution coordinator
│   ├── qa_loop.py           # QA validation loop
│   ├── client.py            # Claude SDK configuration
│   ├── memory.py            # File-based session memory (primary storage)
│   ├── graphiti_memory.py   # Graphiti knowledge graph integration (optional)
│   ├── spec_contract.json   # Spec creation contract (required outputs)
│   ├── prompts/
│   │   ├── planner.md       # Session 1 - creates implementation plan
│   │   ├── coder.md         # Sessions 2+ - implements chunks
│   │   ├── spec_gatherer.md # Requirements gathering agent
│   │   ├── spec_researcher.md # External integration research agent
│   │   ├── spec_writer.md   # Spec document creation agent
│   │   ├── spec_critic.md   # Self-critique agent (ultrathink)
│   │   ├── qa_reviewer.md   # QA validation agent
│   │   └── qa_fixer.md      # QA fix agent
│   └── specs/
│       └── 001-feature/     # Each spec in its own folder
│           ├── spec.md
│           ├── requirements.json     # User requirements (structured)
│           ├── research.json         # External integration research
│           ├── context.json          # Codebase context
│           ├── critique_report.json  # Self-critique findings
│           ├── implementation_plan.json
│           ├── qa_report.md          # QA validation report
│           └── QA_FIX_REQUEST.md     # Issues to fix (if rejected)
└── [your project files]

Key Features

Domain Agnostic: Works for any software project (web apps, APIs, CLIs, etc.)
Multi-Session: Unlimited sessions, each with fresh context
Research-First Specs: External integrations validated against documentation before implementation
Self-Critique: Specs are critiqued using ultrathink to find issues before coding begins
Parallel Execution: 2-3x speedup with multiple workers on independent phases
Isolated Worktrees: Build in a separate workspace - your current work is never touched
Self-Verifying: Agents test their work with browser automation before marking complete
QA Validation Loop: Automated QA agent validates all acceptance criteria before sign-off
Self-Healing: QA finds issues → Fixer agent resolves → QA re-validates (up to 50 iterations)
8-Phase Spec Pipeline: Discovery → Requirements → Research → Context → Spec → Critique → Plan → Validate
Fix Bugs Immediately: Agents fix discovered bugs in the same session, not later
Defense-in-Depth Security: OS sandbox, filesystem restrictions, command allowlist
Secret Scanning: Automatic pre-commit scanning blocks secrets with actionable fix instructions
Human Intervention: Pause, add instructions, or stop at any time
Multiple Specs: Track and run multiple specifications independently
Graphiti Memory (Optional): Persistent knowledge graph for cross-session context retention

Graphiti Memory Integration V2 (Optional)

Auto Claude includes an optional Graphiti-based persistent memory layer that enables context retention across coding sessions. This uses FalkorDB as a graph database to store codebase patterns, session insights, and cross-session learnings.

Why Use Graphiti Memory?

Cross-session context: Agents remember insights from previous sessions
Pattern recognition: Discovered codebase patterns persist and are reusable
Smarter agents: Context retrieval helps agents make better decisions
Historical hints: Spec creation, ideation, and roadmap phases receive relevant historical insights

Multi-Provider Support (V2)

Graphiti Memory V2 supports multiple LLM and embedding providers:

LLM Providers	Embedding Providers
OpenAI (default)	OpenAI (default)
Anthropic	Voyage AI
Azure OpenAI	Azure OpenAI
Ollama (local)	Ollama (local)

Provider Combinations:

OpenAI + OpenAI: Simplest setup, single API key
Anthropic + Voyage: High-quality LLM with specialized embeddings
Ollama + Ollama: Fully offline, no API keys needed
Azure OpenAI + Azure OpenAI: Enterprise deployments

Setup

Step 1: Install the Graphiti dependency

# Uncomment the graphiti line in requirements.txt, or install directly:
pip install graphiti-core[falkordb]

Step 2: Start FalkorDB via Docker

docker-compose up -d falkordb

Step 3: Configure environment variables

Add to your .env file (see .env.example for full documentation):

# Enable Graphiti integration
GRAPHITI_ENABLED=true

# Provider selection (defaults to openai)
GRAPHITI_LLM_PROVIDER=openai
GRAPHITI_EMBEDDER_PROVIDER=openai

# Example 1: OpenAI (simplest)
OPENAI_API_KEY=sk-your-openai-key-here

# Example 2: Anthropic + Voyage (high quality)
# GRAPHITI_LLM_PROVIDER=anthropic
# GRAPHITI_EMBEDDER_PROVIDER=voyage
# ANTHROPIC_API_KEY=sk-ant-xxx
# VOYAGE_API_KEY=pa-xxx

# Example 3: Ollama (fully offline)
# GRAPHITI_LLM_PROVIDER=ollama
# GRAPHITI_EMBEDDER_PROVIDER=ollama
# OLLAMA_LLM_MODEL=deepseek-r1:7b
# OLLAMA_EMBEDDING_MODEL=nomic-embed-text
# OLLAMA_EMBEDDING_DIM=768

Step 4: Verify it's working

python auto-claude/run.py --list
# Should show: "Graphiti memory: ENABLED"

# Test the full integration
python auto-claude/test_graphiti_memory.py

When Disabled

When GRAPHITI_ENABLED is not set (default), Auto Claude uses file-based memory only. This is the zero-dependency default that works out of the box.

Environment Variables

Variable	Required	Description
`CLAUDE_CODE_OAUTH_TOKEN`	Yes	OAuth token from `claude setup-token`
`AUTO_BUILD_MODEL`	No	Model override (default: claude-opus-4-5-20251101)
`GRAPHITI_ENABLED`	No	Set to `true` to enable Graphiti memory
`GRAPHITI_LLM_PROVIDER`	No	LLM provider: openai, anthropic, azure_openai, ollama
`GRAPHITI_EMBEDDER_PROVIDER`	No	Embedder: openai, voyage, azure_openai, ollama
`OPENAI_API_KEY`	For OpenAI	Required for OpenAI provider
`ANTHROPIC_API_KEY`	For Anthropic	Required for Anthropic LLM
`VOYAGE_API_KEY`	For Voyage	Required for Voyage embeddings

See auto-claude/.env.example for complete provider configuration options.

Documentation

For parallel execution details:

How parallelism works
Performance analysis
Best practices
Troubleshooting

See auto-claude/PARALLEL_EXECUTION.md

Acknowledgments

This framework was inspired by Anthropic's Autonomous Coding Agent. Thank you to the Anthropic team for their innovative work on autonomous coding systems.

License

MIT License