adaptationio/auto-claude-cli

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:

1. QA Reviewer checks acceptance criteria
2. If issues found → creates QA_FIX_REQUEST.md
3. QA Fixer applies fixes
4. 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