AIDD - AI Development Driver

Run AI coding agents unattended. Wake up to working features.

AIDD is a headless orchestrator for autonomous AI development sessions. Point it at a project, walk away, and let AI agents implement features while you sleep, eat, or touch grass. It handles iteration loops, failure recovery, idle detection, and progress tracking—so you don't have to babysit the terminal.

Works with OpenCode, KiloCode, or Claude Code CLIs. Your choice.

Why AIDD?

• Unattended Operation: Launch overnight batch runs. AIDD handles retries, timeouts, and stuck agents automatically.
• AutoMaker Compatible: Uses the same .automaker/ metadata format as AutoMaker. Start features in the GUI, finish them headless—or vice versa. Seamless handoff between interactive and batch workflows.
• Structured Progress Tracking: JSON-based feature files, changelogs, and iteration transcripts. Always know what got done and what's left.
• Agent Babysitting Built-In: Two-stage idle timeout nudges stuck agents ("Are you stuck?") before killing them. Consecutive failure limits prevent runaway loops.
• CLI Agnostic: Same workflow whether you're on OpenCode, KiloCode, or Claude Code. Switch providers without changing your process.
• Onboarding for Existing Codebases: Drop AIDD into any project. It analyzes the codebase, generates a spec, and creates a feature backlog automatically.
• Automated Audits: Run comprehensive code audits (security, performance, architecture, etc.) that generate actionable issue backlogs.

Features

• Multiple CLI Support: OpenCode, KiloCode, and Claude Code with unified interface
• AutoMaker Integration: Shared .automaker/ metadata enables GUI↔CLI workflow handoff
• Intelligent Iteration: Automatic retry logic, configurable failure thresholds, idle detection with agent nudging
• Feature-Driven Development: JSON feature files with status tracking, dependencies, and pipeline steps
• Codebase Onboarding: Automatically analyzes existing projects and generates structured metadata
• Shared Directory Sync: Keep IDE configs (.claude, .windsurf, .vscode) synchronized across projects
• Full Transcripts: Every iteration logged for debugging and audit trails
• Audit Mode: Run specialized audits (SECURITY, PERFORMANCE, CODE_QUALITY, etc.) with automatic issue generation

Supported CLIs

OpenCode

• Command: opencode run
• Default CLI if --cli is not specified

KiloCode

• Command: kilocode --mode code --auto
• Specify with --cli kilocode

Claude Code

• Command: claude --print --output-format stream-json --verbose --dangerously-skip-permissions --no-session-persistence
• Specify with --cli claude-code
• Uses your Claude Pro subscription
• No legacy directory (new integration)
• Features:
  • Stream-json output with real-time JSON parsing
  • Formatted console output ([ASSISTANT], [TOOL USE], [TOKENS])
  • Full JSON preserved in transcript files for debugging
  • Token usage tracking including cache hits

Installation

1. Ensure you have one of the supported CLIs installed:
   • OpenCode: Installation instructions
   • KiloCode: Installation instructions
   • Claude Code: Install from claude.com/claude-code
2. Clone or download AIDD to your local machine
3. Make the script executable:

   chmod +x aidd.sh

Usage

Basic Syntax

./aidd.sh [--cli {opencode|kilocode|claude-code}] --project-dir <dir> [OPTIONS]

Required Arguments

• --project-dir DIR: Target project directory

Optional Arguments

• --cli CLI: CLI to use (opencode, kilocode, or claude-code, default: opencode)
• --spec FILE: Specification file (required for new projects)
• --max-iterations N: Number of iterations (unlimited if not specified)
• --timeout N: Timeout in seconds (default: 600)
• --idle-timeout N: Idle timeout in seconds (default: 360)
• --idle-nudge-timeout N: Idle nudge timeout in seconds - sends "are you stuck?" message (default: 180)
• --model MODEL: Model to use (optional)
• --init-model MODEL: Model for initializer/onboarding prompts
• --code-model MODEL: Model for coding prompts
• --no-clean: Skip log cleaning on exit
• --quit-on-abort N: Quit after N consecutive failures (default: 0=continue indefinitely)
• --continue-on-timeout: Continue to next iteration on timeout
• --status: Display project feature list status and exit
• --todo: Use TODO mode (work on todo items instead of new features)
• --validate: Run validation mode to check incomplete features and todos
• --in-progress: Focus only on features with "status": "in_progress"
• --prompt "DIRECTIVE": Use custom directive instead of automatic prompt selection
• --extract-structured: Extract structured JSON from iteration logs after each iteration
• --extract-batch: Batch extract structured JSON from all existing iteration logs and exit
• --check-features: Validate all feature.json files against schema and exit
• --stop-when-done: Stop early when TODO/in-progress mode has no remaining items
• --audit AUDIT[,...]: Run audit mode with one or more audits (e.g., SECURITY or SECURITY,CODE_QUALITY)
• --help: Show help message

Examples

Using OpenCode (Default)

# New project with OpenCode
./aidd.sh --project-dir ./myproject --spec ./specs/myapp.md

# Existing project with specific model
./aidd.sh --project-dir ./myproject --model gpt-4 --max-iterations 5

# Existing project with specific model, in todo prioritizing mode
./aidd.sh --project-dir ./myproject --model gpt-4 --todo

# With different models for init and coding
./aidd.sh --project-dir ./myproject --init-model claude --code-model gpt-4

Using KiloCode

# New project with KiloCode
./aidd.sh --cli kilocode --project-dir ./myproject --spec ./specs/myapp.md

# Existing project
./aidd.sh --cli kilocode --project-dir ./myproject --max-iterations 10

Using Claude Code

# New project with Claude Code
./aidd.sh --cli claude-code --project-dir ./myproject --spec ./specs/myapp.md

# Existing project with specific model
./aidd.sh --cli claude-code --project-dir ./myproject --model sonnet --max-iterations 10

# Using different models for init and coding
./aidd.sh --cli claude-code --project-dir ./myproject --init-model opus --code-model sonnet

Audit Mode

# Run a single audit
./aidd.sh --project-dir ./myproject --audit SECURITY

# Run multiple audits sequentially
./aidd.sh --project-dir ./myproject --audit SECURITY,CODE_QUALITY,ARCHITECTURE

# Audit with limited iterations per audit
./aidd.sh --project-dir ./myproject --audit DEAD_CODE,PERFORMANCE --max-iterations 2

# Available audits: SECURITY, CODE_QUALITY, ARCHITECTURE, PERFORMANCE,
#                   FRONTEND, DATABASE, TESTING, TECHDEBT, DEAD_CODE, and more
# See docs/AUDIT_GUIDE.md for full list

Other Operations

# Display feature list status
./aidd.sh --project-dir ./myproject --status

# Validate feature.json files against schema
./aidd.sh --project-dir ./myproject --check-features

# Run with custom directive (one-shot mode)
./aidd.sh --project-dir ./myproject --prompt "perform a security audit" --max-iterations 1

# Extract structured logs from all iterations
./aidd.sh --project-dir ./myproject --extract-batch

Workflows

New Project Workflow

For empty or non-existent directories:

1. Creates project directory if it doesn't exist
2. Copies scaffolding files from scaffolding/ directory
3. Copies templates into project-dir/.automaker/
4. Copies spec file to .automaker/app_spec.txt (if --spec is provided)
5. Uses initializer prompt to set up initial project structure
6. Creates features/*/feature.json based on the provided spec

Existing Codebase Workflow

For directories containing code but no .automaker/ files:

1. Skips copying scaffolding files
2. Does NOT copy spec file
3. Uses onboarding prompt to:
   • Analyze existing codebase
   • Generate app_spec.txt based on discovered functionality
   • Create features/*/feature.json with existing features marked as complete
   • Document project structure and technical debt

Subsequent Iterations

Once onboarding artifacts exist (app_spec.txt, features/, CHANGELOG.md):

• Uses coding prompt for continued development
• Implements remaining features from the feature list

Audit Mode Workflow

Run specialized code audits that generate actionable issue backlogs:

1. Audit Selection: Choose from 20+ audit types (SECURITY, PERFORMANCE, CODE_QUALITY, etc.)
2. Multi-Audit Support: Combine audits with commas: --audit SECURITY,CODE_QUALITY
3. Sequential Execution: Each audit runs independently with its own iterations
4. Issue Generation: Creates feature.json files for each finding in .automaker/features/audit-{name}-*/
5. Audit Reports: Generates detailed reports in .automaker/audit-reports/

See docs/AUDIT_GUIDE.md for the complete audit catalog and recommendations.

Shared Resource Synchronization

AIDD can automatically synchronize shared configuration directories and files to projects at the start of each iteration. This ensures all projects have the latest IDE configurations, linting rules, or other shared resources.

Directory Sync (copydirs.txt)

Create a copydirs.txt file in the AIDD directory with one absolute path per line:

# copydirs.txt example
/d/applications/.claude
/d/applications/.windsurf
/home/user/.vscode

Behavior:

• Runs at the start of each iteration before the CLI prompt
• Uses rsync -av --delete (falls back to cp -R if rsync unavailable)
• Logs which directories were refreshed
• Skips missing source directories with a warning

File Sync (copyfiles.txt)

Create a copyfiles.txt file in the AIDD directory for individual files:

# copyfiles.txt example - simple format (copies to project root)
/d/applications/shared/.prettierrc
/d/applications/shared/.editorconfig

# With custom target path (source -> target)
/d/applications/configs/tsconfig.base.json -> configs/tsconfig.base.json
/home/user/templates/eslintrc.json -> .eslintrc.json

Behavior:

• Runs at the start of each iteration after directory sync
• Simple format places file in project root with same filename
• Arrow format (->) specifies custom relative target path
• Creates target directories as needed
• Logs which files were refreshed

Common Use Cases

• Syncing IDE configuration (.vscode, .windsurf, .claude)
• Sharing linting rules across projects
• Distributing common scripts or templates
• Keeping project guidelines up to date
• Sharing individual config files (.prettierrc, .editorconfig, LICENSE)

Project Structure

aidd/
├── aidd.sh                 # Main script
├── copydirs.txt           # List of shared directories to sync to projects
├── copyfiles.txt          # List of shared files to sync to projects
├── lib/
│   ├── args.sh            # Argument parsing
│   ├── cli-claude-code.sh # Claude Code CLI implementation
│   ├── cli-factory.sh     # CLI abstraction layer
│   ├── cli-kilocode.sh    # KiloCode CLI implementation
│   ├── cli-opencode.sh    # OpenCode CLI implementation
│   ├── config.sh          # Configuration constants
│   ├── iteration.sh       # Iteration handling
│   ├── json-parser.sh     # JSON stream parser for Claude Code
│   ├── log-cleaner.sh     # Native bash log cleaning
│   ├── project.sh         # Project management
│   └── utils.sh           # Utility functions
├── prompts/
│   ├── _common/           # Shared prompt modules (refactored v2.0)
│   │   ├── assistant-rules-loading.md
│   │   ├── project-overrides.md
│   │   ├── testing-requirements.md
│   │   ├── file-integrity.md
│   │   ├── hard-constraints.md
│   │   ├── tool-selection-guide.md
│   │   └── error-handling-patterns.md
│   ├── onboarding.md      # Onboarding prompt (existing codebases)
│   ├── initializer.md     # Initializer prompt (new projects)
│   ├── coding.md          # Coding prompt (development iterations)
│   └── todo.md            # TODO mode prompt
├── audits/                # Audit definition files
│   ├── SECURITY.md        # Security audit guidelines
│   ├── PERFORMANCE.md     # Performance audit guidelines
│   ├── CODE_QUALITY.md    # Code quality audit
│   └── ...                # 20+ specialized audits
├── docs/
│   └── AUDIT_GUIDE.md     # Audit selection guide
├── scaffolding/           # Template files for new projects
├── templates/             # Project metadata templates
└── specs/                 # Specification examples

Project Metadata (.automaker/):
.automaker/
├── app_spec.txt           # Project specification
├── CHANGELOG.md           # Progress log (Keep a Changelog format)
├── features/              # Feature tracking (one dir per feature)
│   ├── feature-*/         # Regular features
│   └── audit-*/           # Audit-generated issues
├── audit-reports/         # Audit summary reports
├── audits/                # Referenced audit guidelines (runtime copy)
├── todo.md                # TODO items
├── project_structure.md   # Architecture documentation
└── iterations/            # Iteration logs
    ├── 001.log
    ├── 002.log
    └── ...

How It Works

1. CLI Initialization: Determines which CLI to use (OpenCode or KiloCode)
2. Project Detection: Detects if the target directory is an existing codebase
3. Metadata Setup: Creates or migrates .automaker directory
4. Iteration Loop: Runs in a loop based on --max-iterations:
   • Determines appropriate prompt (onboarding, initializer, or coding)
   • Executes prompt through selected CLI
   • Captures transcript to numbered log file
   • Handles failures with retry logic
5. Log Cleanup: Optionally cleans up iteration logs on exit

Iteration Transcripts

Each iteration writes a transcript file under:

project-dir/.automaker/iterations/001.log
project-dir/.automaker/iterations/002.log
...

The transcript captures the console output for that iteration. The log index is chosen as the next number after the highest existing numeric *.log in that directory, so logs are never overwritten across re-runs.

CLI Abstraction

AIDD uses a factory pattern to abstract CLI differences:

• cli-factory.sh: Provides unified interface (run_cli_prompt, check_cli_available, etc.)
• cli-opencode.sh: OpenCode-specific implementation
• cli-kilocode.sh: KiloCode-specific implementation
• cli-claude-code.sh: Claude Code-specific implementation

This allows the same codebase to support all CLIs with minimal differences.

Error Handling

AIDD includes comprehensive error handling:

• Exit Codes: 0 (success), 1 (general error), 2 (invalid args), 70 (no assistant), 71 (idle timeout), 72 (provider error), 124 (signal terminated)
• Retry Logic: Configurable with --quit-on-abort
• Two-Stage Idle Timeout: When an agent becomes unresponsive:
  • Stage 1: After idle-nudge-timeout (default 180s), sends "are you stuck?" message to the agent
  • Stage 2: If still no response after remaining time, terminates the session
  • Total timeout is still controlled by --idle-timeout (default 360s)
• Timeout Detection: Monitors both overall timeout and idle timeout
• Provider Error Detection: Detects and handles API errors gracefully

Requirements

• Bash 4.0+
• One of the supported CLIs installed and in PATH:
  • OpenCode (opencode)
  • KiloCode (kilocode)
  • Claude Code (claude)
• jq (required for Claude Code JSON parsing; also required for --status and --check-features)
• rsync (optional, for shared directory synchronization - falls back to cp if unavailable)

Version History

• v2.3.0 (2026-01-15):
  • Added audit mode with 20+ specialized audits (SECURITY, PERFORMANCE, etc.)
  • Multi-audit support: run multiple audits sequentially with comma-separated names
  • Audit cross-reference support: referenced audit files copied to target project
  • Automatic issue deduplication during audits
  • Added --stop-when-done flag for TODO/in-progress modes
  • Added comprehensive AUDIT_GUIDE.md documentation
• v2.2.0 (2026-01-09):
  • Added Claude Code CLI support with stream-json parsing
  • Implemented JSON parser for readable console output
  • Added token usage tracking for Claude Code
  • Updated all documentation to reflect triple CLI support
• v2.1.0 (2026-01-09):
  • Added two-stage idle timeout with agent nudging feature
  • Added shared directory synchronization (copydirs.txt)
  • Refactored prompts to modular architecture (see prompts/PROMPT_CHANGELOG.md)
  • Fixed CLI name display bug in error messages
  • Fixed coprocess file descriptor handling in nudge feature
• v2.0.0 (2026-01-08): Unified AIDD supporting both OpenCode and KiloCode
• v1.1.0: aidd-o (OpenCode) and aidd-k (KiloCode) as separate projects
• v1.0.0: Initial aidd-o release

Architecture

AIDD follows a modular architecture with clear separation of concerns:

1. Configuration Layer (config.sh): Defines all constants and defaults
2. Utility Layer (utils.sh): Provides logging, file operations, and helpers
3. CLI Abstraction Layer (cli-factory.sh, *-cli.sh): Abstracts CLI differences
4. Business Logic Layer (args.sh, project.sh, iteration.sh): Core functionality
5. Main Script (aidd.sh): Orchestrates everything

Support

For issues or questions:

1. Check the --help output
2. Review iteration logs in .automaker/iterations/
3. Check CLI-specific documentation:
   • OpenCode: opencode.ai/docs
   • KiloCode: kilocode.ai/docs
   • Claude Code: claude.com/claude-code