Auto Code Advanced Usage

This document covers advanced usage patterns for power users who want to customize and optimize their Auto Code experience. If you're new to Auto Code, start with the Quick Start Guide or CLI Usage Guide.

Parallel Execution
Agent Customization
Memory System
LLM Provider Configuration
Third-Party Integrations
QA Customization
Interactive Controls
Workspace Best Practices

Parallel Execution

Auto Code supports running multiple specs in parallel and can spawn subagents for concurrent subtask work.

Running Multiple Specs Simultaneously

You can run multiple specs at the same time from different terminal windows:

# Terminal 1
cd apps/backend
python run.py --spec 001-auth

# Terminal 2
cd apps/backend
python run.py --spec 002-dashboard

# Terminal 3
cd apps/backend
python run.py --spec 003-api-endpoints

Resource Requirements:

Each active spec consumes ~500MB RAM
CPU usage scales with agent activity
Network bandwidth depends on LLM provider

Best Practices:

Start with 2-3 parallel specs
Monitor system resources
Avoid parallel specs that modify the same files
Use for independent features only

Subagent Spawning

The Coder agent automatically spawns subagents for parallelizable subtasks:

# Example: Implementing a feature with independent components
Task: "Add user authentication with OAuth, registration, and password reset"

# Agent may spawn subagents for:
# - Subagent 1: OAuth integration (Google, GitHub)
# - Subagent 2: Registration form and validation
# - Subagent 3: Password reset flow

How it Works:

Planner identifies independent subtasks in implementation plan
Coder creates subagent sessions for parallel work
Each subagent works on isolated files/components
Coder merges all subagent results

Configuration:

# Maximum concurrent subagents (default: 4)
# Set in apps/backend/.env
MAX_SUBAGENTS=4

Agent Customization

You can customize agent behavior by modifying system prompts or creating custom agents.

Modifying Agent Prompts

All agent prompts live in apps/backend/prompts/:

apps/backend/prompts/
├── planner.md           # Creates implementation plans
├── coder.md             # Implements subtasks
├── coder_recovery.md    # Recovers from stuck states
├── qa_reviewer.md       # Validates acceptance criteria
├── qa_fixer.md          # Fixes QA-reported issues
├── spec_gatherer.md     # Collects requirements
├── spec_researcher.md   # Validates external integrations
├── spec_writer.md       # Creates spec.md documents
└── spec_critic.md       # Self-critique and refinement

Example: Customizing the Coder Agent

Read the existing prompt:

cat apps/backend/prompts/coder.md

Make your modifications:

# Add custom coding standards
## Coding Standards
- Follow PEP 8 for Python code
- Use TypeScript strict mode
- Add JSDoc comments to all functions
- Write tests for all new features

# Add project-specific patterns
## Project-Specific Patterns
- Use React Query for data fetching
- Follow the existing component structure in src/components/
- Add error handling with try-catch blocks

Restart Auto Code to apply changes

Best Practices:

Keep prompts focused on the agent's role
Provide examples in prompts
Test modifications on simple specs first
Document your changes in prompt comments

Creating Custom Agents

For specialized workflows, you can create custom agents:

Create a new prompt file:

# Example: Performance optimization specialist
apps/backend/prompts/optimizer.md

Define the agent role and behavior:

# Performance Optimizer Agent

You are a performance optimization specialist. Your role is to:
1. Analyze code for performance bottlenecks
2. Propose optimizations with trade-offs
3. Implement approved optimizations
4. Benchmark before/after results

## Optimization Principles
- Profile before optimizing
- Prioritize user-facing improvements
- Document trade-offs clearly
- Avoid premature optimization

Integrate into the workflow:

# In your custom run.py or agent orchestration
from agents.custom_agent import CustomOptimizerAgent

optimizer = CustomOptimizerAgent(
    project_dir=project_dir,
    spec_dir=spec_dir
)
optimizer.run()

Memory System

Auto Code uses Graphiti to maintain a knowledge graph across sessions, storing patterns, gotchas, and discoveries.

How Memory Works

The memory system automatically:

Extracts patterns from each agent session
Stores code relationships and dependencies
Remembers what worked and what didn't
Provides context to future sessions

Memory Storage:

# Memory data lives in spec directories
.auto-claude/specs/XXX/graphiti/
├── graphiti.db          # Knowledge graph database
├── embeddings/          # Vector embeddings for search
└── insights/            # Extracted session insights

Configuring Memory Providers

Memory supports multiple LLM and embedding providers:

OpenAI (Recommended):

# In apps/backend/.env
GRAPHITI_ENABLED=true
GRAPHITI_LLM_PROVIDER=openai
GRAPHITI_EMBEDDER_PROVIDER=openai
OPENAI_API_KEY=sk-...

Anthropic Claude:

GRAPHITI_ENABLED=true
GRAPHITI_LLM_PROVIDER=anthropic
GRAPHITI_EMBEDDER_PROVIDER=voyage
ANTHROPIC_API_KEY=sk-ant-...
VOYAGE_API_KEY=sk-voyage-...

Ollama (Local, Free):

GRAPHITI_ENABLED=true
GRAPHITI_LLM_PROVIDER=ollama
GRAPHITI_EMBEDDER_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434

Inspecting Memory

View what the memory system has learned:

# View recent insights
cat .auto-claude/specs/XXX/graphiti/insights/latest.json

# Search memory programmatically
cd apps/backend
python -c "
from integrations.graphiti.memory import get_graphiti_memory
memory = get_graphiti_memory('specs/XXX', '.')
results = memory.search('authentication patterns')
print(results)
"

Managing Memory

Disable Memory (Not Recommended):

# In apps/backend/.env
GRAPHITI_ENABLED=false

Clear Memory:

# Delete memory for a specific spec
rm -rf .auto-claude/specs/XXX/graphiti/

# Memory will rebuild on next run

Best Practices

Keep memory enabled - improves agent performance over time
Use OpenAI or Voyage embeddings - best quality
Local development - Ollama is free and private
Production - Use hosted providers for reliability
Cost management - Memory adds ~10% to API costs

LLM Provider Configuration

Auto Code supports multiple LLM providers beyond Claude. This is useful for:

Cost optimization (mix and match providers)
Redundancy and failover
Feature-specific model selection

Supported Providers

Provider	Models	Use Case	Cost (per 1M tokens)
Claude	Opus 4.5, Sonnet 4.5	Best reasoning, complex tasks	$15-$75
OpenAI	GPT-4o, GPT-4o-mini	Fast, cost-effective	$2.5-$5
Google	Gemini 2.5 Pro	Multimodal, long context	Variable
Azure OpenAI	GPT-4 variants	Enterprise, compliance	Variable
Ollama	Llama 3, Mistral	Local, private	Free

Configuring Alternative Providers

Note: The Claude Code OAuth token is always required for the agent SDK, but you can use alternative providers for specific tasks.

OpenAI (for memory system):

# apps/backend/.env
GRAPHITI_LLM_PROVIDER=openai
GRAPHITI_EMBEDDER_PROVIDER=openai
OPENAI_API_KEY=sk-...

Ollama (local models):

# Install Ollama
ollama pull llama3.2
ollama pull mistral

# Configure
GRAPHITI_LLM_PROVIDER=ollama
GRAPHITI_EMBEDDER_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_LLM_MODEL=mistral
OLLAMA_EMBEDDER_MODEL=nomic-embed-text

Google Gemini:

GRAPHITI_LLM_PROVIDER=google
GRAPHITI_EMBEDDER_PROVIDER=google
GOOGLE_API_KEY=...

Cost Optimization Strategy

Tiered Approach:

Claude Opus - For planning, complex architecture (highest quality)
Claude Sonnet - For coding, QA (balanced cost/quality)
OpenAI GPT-4o-mini - For memory embeddings (cheapest)
Ollama - For local development (free)

Example Configuration:

# Use Claude for agents, OpenAI for memory
AUTO_BUILD_MODEL=claude-sonnet-4-5-20250929
GRAPHITI_LLM_PROVIDER=openai
GRAPHITI_EMBEDDER_PROVIDER=openai
OPENAI_API_KEY=sk-...

Third-Party Integrations

Auto Code integrates with GitHub, GitLab, and Linear for issue tracking and progress management.

GitHub Integration

Setup:

Create GitHub Personal Access Token:
- Go to https://github.com/settings/tokens
- Generate token with repo, issues, pull_requests scopes
Configure Auto Code:

# apps/backend/.env
GITHUB_TOKEN=ghp_...
GITHUB_DEFAULT_BRANCH=main

Features:

Import GitHub issues as specs
Create PRs from completed builds
Update issue status automatically
Link specs to issues

Usage:

# Import issue as spec
cd apps/backend
python runners/github_import.py --issue 123

# Create PR after merge
python run.py --spec 001 --create-pr

GitLab Integration

Setup:

# apps/backend/.env
GITLAB_TOKEN=glpat-...
GITLAB_INSTANCE_URL=https://gitlab.com  # or self-hosted

Features:

Import GitLab issues
Create merge requests
Update issue status

Linear Integration

Setup:

Get Linear API key:
- Go to https://linear.app/settings/api
- Create personal API key
Configure:

# apps/backend/.env
LINEAR_API_KEY=lin_...

Features:

Import Linear issues as specs
Sync spec status back to Linear
Create Linear issues from QA failures

Desktop UI Import:

Open Auto Code desktop app
Click "Import from Linear"
Select issues to import
Specs created automatically

QA Customization

Tailor the QA validation loop to your project's standards and requirements.

Custom QA Criteria

Modify the QA reviewer prompt to add custom checks:

# Edit apps/backend/prompts/qa_reviewer.md

Add Custom Validation:

## Custom Validation Rules

### Security Checklist
- [ ] No hardcoded secrets or API keys
- [ ] User input is sanitized
- [ ] Authentication is properly implemented
- [ ] SQL injection protection in place

### Performance Checklist
- [ ] No N+1 queries
- [ ] Images are optimized
- [ ] Caching strategy implemented
- [ ] Bundle size under 500KB

### Accessibility Checklist
- [ ] ARIA labels on interactive elements
- [ ] Keyboard navigation works
- [ ] Color contrast meets WCAG AA
- [ ] Screen reader compatible

Custom Test Commands

Add project-specific test commands to QA:

# Edit .auto-claude/specs/XXX/implementation_plan.json

{
  "verification_strategy": {
    "test_types_required": ["unit", "integration"],
    "commands": {
      "unit_tests": "pytest tests/unit/ -v",
      "integration_tests": "pytest tests/integration/ -v",
      "e2e_tests": "npm run test:e2e",
      "linting": "eslint src/ && black apps/backend/",
      "type_check": "tsc --noEmit && mypy apps/backend/"
    }
  }

E2E Testing with Electron

For frontend changes, QA agents can perform automated E2E testing:

# Enable Electron MCP
# apps/backend/.env
ELECTRON_MCP_ENABLED=true
ELECTRON_DEBUG_PORT=9222

# Start Electron with debugging
npm run dev

# Run QA - will automatically test UI
python run.py --spec 001 --qa

Capabilities:

Take screenshots
Click buttons/links
Fill forms
Navigate routes
Verify elements exist

Interactive Controls

Intervene in agent sessions to provide guidance, fix issues, or change direction.

Pause and Resume

Keyboard Controls (CLI):

# While agent is running:
Ctrl+C (once)  # Pause after current session
Ctrl+C (twice) # Exit immediately

File-Based Controls:

# Pause after current session
touch .auto-claude/specs/XXX/PAUSE

# Resume
rm .auto-claude/specs/XXX/PAUSE

Human Input

Provide guidance to agents during builds:

# Create instruction file
echo "Focus on the authentication bug first, ignore dashboard for now" > .auto-claude/specs/XXX/HUMAN_INPUT.md

# Agent reads instructions on next session

Example Scenarios:

Change implementation approach mid-build
Prioritize specific subtasks
Skip certain components
Request different architecture

Session Interruption

Pause builds to review progress or fix issues:

# Trigger PAUSE
touch .auto-claude/specs/001-feature/PAUSE

# Wait for agent to finish current session

# Review progress
cat .auto-claude/specs/001-feature/build-progress.txt

# Add guidance
echo "The approach looks good, but use Redux instead of Context API" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

# Resume
rm .auto-claude/specs/001-feature/PAUSE

Workspace Best Practices

Advanced strategies for managing Git worktrees and merging builds.

Merge Strategies

Approach 1: Test Before Merge

# 1. Run build
python run.py --spec 001

# 2. Test in worktree
cd .worktrees/auto-code-001-feature/
npm run dev
# Manual testing...

# 3. Review changes
cd apps/backend
python run.py --spec 001 --review

# 4. Merge if satisfied
python run.py --spec 001 --merge

Approach 2: Parallel Testing

# Test multiple builds simultaneously
cd .worktrees/auto-code-001-feature/
npm run dev &

cd .worktrees/auto-code-002-feature/
npm run dev &

# Compare both implementations

Approach 3: Incremental Merge

# Merge specific files manually
cd .worktrees/auto-code-001-feature/
git checkout main -- package.json  # Keep original

cd apps/backend
python run.py --spec 001 --merge
# Resolve conflicts interactively

Worktree Management

List All Worktrees:

git worktree list

Clean Up Old Worktrees:

# Remove worktree after merge
git worktree remove .worktrees/auto-code-001-feature

# Or prune all merged worktrees
git worktree prune

Switch Between Worktrees:

# Work on build 1
cd .worktrees/auto-code-001-feature/
npm run dev

# Work on build 2
cd .worktrees/auto-code-002-feature/
npm run dev

Handling Merge Conflicts

When conflicts arise during merge:

# 1. Review conflicts
python run.py --spec 001 --merge

# 2. Auto Code pauses for conflict resolution

# 3. Resolve conflicts manually
cd .worktrees/auto-code-001-feature/
# Edit conflicted files...

# 4. Mark as resolved
git add <resolved-files>
git commit --no-edit

# 5. Return to backend
cd apps/backend

# 6. Continue merge
python run.py --spec 001 --merge

When to Discard Builds

Scenarios for Discarding:

Wrong implementation approach
Test coverage insufficient
Performance issues discovered
Better alternative identified

# Discard build completely
python run.py --spec 001 --discard

# Build is deleted, worktree cleaned up

Tip: Review the build before discarding to learn from the agent's approach:

# Review even if discarding
python run.py --spec 001 --review

# Read agent's thought process
cat .auto-claude/specs/001/build-progress.txt

# Then discard
python run.py --spec 001 --discard

Performance Optimization

Optimize Auto Code for faster builds and lower costs.

Reduce API Costs

Use Smaller Models:

# Use Sonnet instead of Opus for simpler tasks
AUTO_BUILD_MODEL=claude-sonnet-4-5-20250929

Limit Iterations:

# Stop after 5 QA iterations (default: 50)
python run.py --spec 001 --max-qa-iterations 5

Skip QA for Simple Changes:

# Skip QA loop for text changes, simple fixes
python run.py --spec 001 --skip-qa

Speed Up Builds

Parallel Subagents:

# Increase subagent limit (default: 4)
MAX_SUBAGENTS=8

Reduce Context Window:

# Use smaller context for faster token processing
# In apps/backend/core/client.py
max_tokens=4000  # instead of 8000

Cache Dependencies:

# Use local caching for faster iterations
# Ollama for memory (no API calls)
GRAPHITI_LLM_PROVIDER=ollama

Troubleshooting Advanced Issues

See the Troubleshooting Guide for solutions to common issues.

Debug Mode

Enable detailed logging for debugging:

# apps/backend/.env
DEBUG=true
LOG_LEVEL=debug

Agent Recovery

If an agent gets stuck:

# 1. Pause the build
touch .auto-claude/specs/XXX/PAUSE

# 2. Review progress
cat .auto-claude/specs/XXX/build-progress.txt

# 3. Add recovery instructions
echo "The agent is stuck on X, try approach Y instead" > .auto-claude/specs/XXX/HUMAN_INPUT.md

# 4. Resume
rm .auto-claude/specs/XXX/PAUSE

# Agent will read HUMAN_INPUT.md and adjust

Subtask Recovery

Retry specific subtasks:

# Edit implementation_plan.json
# Set subtask status from "completed" to "pending"

# Resume build
python run.py --spec XXX

FilesExpand file tree

ADVANCED-USAGE.md

Latest commit

History

ADVANCED-USAGE.md

File metadata and controls

Auto Code Advanced Usage

Table of Contents

Parallel Execution

Running Multiple Specs Simultaneously

Subagent Spawning

Agent Customization

Modifying Agent Prompts

Creating Custom Agents

Memory System

How Memory Works

Configuring Memory Providers

Inspecting Memory

Managing Memory

Best Practices

LLM Provider Configuration

Supported Providers

Configuring Alternative Providers

Cost Optimization Strategy

Third-Party Integrations

GitHub Integration

GitLab Integration

Linear Integration

QA Customization

Custom QA Criteria

Custom Test Commands

E2E Testing with Electron

Interactive Controls

Pause and Resume

Human Input

Session Interruption

Workspace Best Practices

Merge Strategies

Worktree Management

Handling Merge Conflicts

When to Discard Builds

Performance Optimization

Reduce API Costs

Speed Up Builds

Troubleshooting Advanced Issues

Debug Mode

Agent Recovery

Subtask Recovery

Further Reading