Skip to content

CLI-USAGE.md

Latest commit

 

History

History
173 lines (119 loc) · 3.86 KB

CLI-USAGE.md

File metadata and controls

173 lines (119 loc) · 3.86 KB

Auto Claude CLI Usage

This document covers terminal-only usage of Auto Claude. For most users, we recommend using the Desktop UI instead - it provides a better experience with visual task management, progress tracking, and automatic Python environment setup.

When to Use CLI

  • You prefer terminal workflows
  • You're running on a headless server
  • You're integrating Auto Claude into scripts or CI/CD

Prerequisites

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

Setup

Step 1: Navigate to the auto-claude directory

cd auto-claude

Step 2: Set up Python environment

# 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

Creating Specs

# Activate the virtual environment
source .venv/bin/activate

# Create a spec interactively
python spec_runner.py --interactive

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

# Force a specific complexity level
python spec_runner.py --task "Fix button color" --complexity simple

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

Complexity Tiers

The spec runner automatically assesses task complexity:

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

Running Builds

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

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

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

QA Validation

After all chunks are complete, QA validation runs automatically:

# Skip automatic QA
python run.py --spec 001 --skip-qa

# Run QA validation manually
python run.py --spec 001 --qa

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

The QA validation loop:

  1. QA Reviewer checks all 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

Auto Claude uses Git worktrees for isolated builds:

# 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 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

Interactive Controls

While the agent is running:

# Pause and add instructions
Ctrl+C (once)

# Exit immediately
Ctrl+C (twice)

File-based alternative:

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

# Add instructions
echo "Focus on fixing the login bug first" > specs/001-name/HUMAN_INPUT.md

Spec Validation

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

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)

Auto Claude Memory Layer (Optional)

For cross-session context retention, see the main README for Memory Layer setup instructions.

Verifying Memory Layer

cd auto-claude
source .venv/bin/activate
python test_graphiti_memory.py