Auto-Claude CLI
Complete command-line interface reference for Auto-Claude autonomous coding framework.
Quick Reference
| Command | Purpose |
|---|
python spec_runner.py --interactive | Create spec interactively |
python spec_runner.py --task "..." | Create spec from description |
python run.py --spec 001 | Run autonomous build |
python run.py --list | List all specs |
python run.py --spec 001 --review | Review changes |
python run.py --spec 001 --merge | Merge to project |
Setup
All CLI commands run from apps/backend/:
cd Auto-Claude/apps/backend
# Activate virtual environment
source .venv/bin/activate # Linux/macOS
# OR
.venv\Scripts\activate # Windows
Core Commands
Creating Specs
# Interactive spec creation (recommended for complex tasks)
python spec_runner.py --interactive
# Quick spec from task description
python spec_runner.py --task "Add user authentication with OAuth"
# Force complexity level
python spec_runner.py --task "Fix button color" --complexity simple
python spec_runner.py --task "Add dark mode" --complexity standard
python spec_runner.py --task "Implement payment system" --complexity complex
# Continue an interrupted spec creation
python spec_runner.py --continue 001-feature-name
Complexity Tiers
| Tier | Phases | When Used |
|---|
| SIMPLE | 3 | 1-2 files, single service, no integrations (UI fixes, text changes) |
| STANDARD | 6-7 | 3-10 files, 1-2 services, minimal integrations (features, bug fixes) |
| COMPLEX | 8 | 10+ files, multiple services, external integrations |
Running Builds
# List all specs and their status
python run.py --list
# Run a specific spec (by number or full name)
python run.py --spec 001
python run.py --spec 001-feature-name
# Limit iterations for testing
python run.py --spec 001 --max-iterations 5
# Skip automatic QA
python run.py --spec 001 --skip-qa
QA Validation
# Run QA validation manually
python run.py --spec 001 --qa
# Check QA status
python run.py --spec 001 --qa-status
The QA loop:
- QA Reviewer checks acceptance criteria
- If issues found → creates
QA_FIX_REQUEST.md - QA Fixer applies fixes
- Loop repeats until approved (up to 50 iterations)
Workspace Management
# Test the feature in isolated workspace
cd .worktrees/auto-claude/{spec-name}/
npm run dev # or your project's run command
# Return to backend for management commands
cd apps/backend
# See what was changed
python run.py --spec 001 --review
# Merge changes into your project
python run.py --spec 001 --merge
# Discard if you don't like it
python run.py --spec 001 --discard
Spec Validation
# Validate a spec against all checkpoints
python validate_spec.py --spec-dir specs/001-feature --checkpoint all
# Validate specific checkpoint
python validate_spec.py --spec-dir specs/001-feature --checkpoint requirements
Interactive Controls
During Build
# Pause and add instructions (press once)
Ctrl+C
# Exit immediately (press twice)
Ctrl+C Ctrl+C
File-Based Control
# Pause after current session
touch specs/001-name/PAUSE
# Add human instructions
echo "Focus on fixing the login bug first" > specs/001-name/HUMAN_INPUT.md
# Remove pause to continue
rm specs/001-name/PAUSE
Environment Variables
| Variable | Required | Default | Description |
|---|
CLAUDE_CODE_OAUTH_TOKEN | Yes | - | OAuth token from claude setup-token |
AUTO_BUILD_MODEL | No | claude-opus-4-5-20251101 | Model override |
DEFAULT_BRANCH | No | auto-detect | Base branch for worktrees |
DEBUG | No | false | Enable debug logging |
DEBUG_LEVEL | No | 1 | Debug verbosity (1-3) |
GRAPHITI_ENABLED | No | true | Enable memory system |
LINEAR_API_KEY | No | - | Linear integration |
Command Options
spec_runner.py
| Option | Description |
|---|
--interactive | Interactive spec creation mode |
--task "..." | Create spec from task description |
--complexity LEVEL | Force complexity (simple/standard/complex) |
--continue SPEC | Continue interrupted spec creation |
run.py
| Option | Description |
|---|
--spec SPEC | Run or manage specific spec |
--list | List all specs with status |
--review | Show changes in worktree |
--merge | Merge changes to project |
--discard | Delete build (with confirmation) |
--qa | Run QA validation |
--qa-status | Check QA status |
--skip-qa | Skip automatic QA |
--max-iterations N | Limit build iterations |
Workflow Examples
Complete Feature Development
# 1. Create spec
python spec_runner.py --task "Add user profile page with avatar upload"
# 2. Run build (finds latest spec automatically)
python run.py --spec 001
# 3. Review changes in isolated workspace
python run.py --spec 001 --review
# 4. Test in worktree
cd .worktrees/auto-claude/001-user-profile/
npm run dev
# 5. Merge to project
cd ../../../apps/backend
python run.py --spec 001 --merge
Quick Bug Fix
# Simple fix with minimal phases
python spec_runner.py --task "Fix login button alignment" --complexity simple
# Run and merge
python run.py --spec 002
python run.py --spec 002 --merge
Batch Processing
# Create multiple specs
python spec_runner.py --task "Add search functionality"
python spec_runner.py --task "Add filters to search"
python spec_runner.py --task "Add search history"
# Run them in sequence
python run.py --spec 001
python run.py --spec 002
python run.py --spec 003
Spec Directory Structure
Each spec creates a directory in .auto-claude/specs/XXX-name/:
001-feature-name/
├── spec.md # Feature specification
├── requirements.json # Structured requirements
├── context.json # Discovered codebase context
├── implementation_plan.json # Subtask-based plan
├── qa_report.md # QA validation results
├── QA_FIX_REQUEST.md # Issues to fix (if rejected)
├── PAUSE # Pause file (if present)
└── HUMAN_INPUT.md # Human instructions
Tips for Effective Use
Writing Good Task Descriptions
# Good: Specific and actionable
python spec_runner.py --task "Add user authentication with Google OAuth, including login button on header and protected routes for /dashboard/*"
# Bad: Vague
python spec_runner.py --task "Add login"
Choosing Complexity
- Simple: Single file changes, UI tweaks, text updates
- Standard: Most features, bug fixes, component additions
- Complex: Multi-service changes, external integrations, architectural changes
Debugging Failed Builds
# Enable verbose logging
DEBUG=true DEBUG_LEVEL=3 python run.py --spec 001
# Check spec status
python run.py --list
# Review QA report
cat .auto-claude/specs/001-feature/qa_report.md
Related Skills
- auto-claude-spec: Detailed spec creation workflow
- auto-claude-build: Build process deep dive
- auto-claude-workspace: Workspace management
- auto-claude-troubleshooting: Debugging issues
