AI Dev Pipeline (aidp) - Ruby Gem

A portable CLI that automates a complete AI development workflow from idea to implementation using your existing IDE assistants. Now with Enhanced TUI - a rich terminal interface that runs complete workflows with intelligent provider management and error recovery.

# Install the gem
gem install aidp

# Navigate to your project
cd /your/project

# Start the interactive TUI (default)
aidp

On the first run in a project without an aidp.yml, AIDP now launches a First-Time Setup Wizard instead of failing with a configuration error. You'll be prompted to choose one of:

1. Minimal (single provider: cursor)
2. Development template (multiple providers, safe defaults)
3. Production template (full-feature example – review before committing)
4. Full example (verbose documented config)
5. Custom (interactive prompts for providers and defaults)

Non-interactive environments (CI, scripts, pipes) automatically receive a minimal aidp.yml so workflows can proceed without manual intervention.

You can re-run the wizard manually by removing aidp.yml and starting aidp again.

AIDP features a rich terminal interface that transforms it from a step-by-step tool into an intelligent development assistant. The enhanced TUI provides beautiful, interactive terminal components while running complete workflows automatically.

• 🎨 Rich Terminal Interface: Beautiful CLI UI components with progress bars, spinners, and frames
• 📋 Interactive Navigation: Hierarchical menu system with breadcrumb navigation
• ⌨️ Keyboard Shortcuts: Full keyboard navigation and control
• 📊 Real-time Progress: Live monitoring of progress and system status
• 🔄 Workflow Control: Pause, resume, cancel, and stop workflows with visual feedback
• 💬 Smart Question Collection: Interactive prompts with validation and error handling

# Start the interactive TUI (default)
aidp

# Show version information
aidp --version

# Show help information
aidp --help

AIDP intelligently manages multiple providers with automatic switching:

• Claude API - Primary provider for complex analysis and code generation
• Gemini API - Cost-effective fallback for general tasks
• Cursor CLI - IDE-integrated provider for code-specific tasks

The TUI automatically switches providers when:

• Rate limits are hit
• Providers fail or timeout
• Cost limits are reached
• Performance optimization is needed

# aidp.yml
providers:
  claude:
    type: "usage_based"
    api_key: "${AIDP_CLAUDE_API_KEY}"
    max_tokens: 100000
  gemini:
    type: "usage_based"
    api_key: "${AIDP_GEMINI_API_KEY}"
    max_tokens: 50000
  cursor:
    type: "subscription"

# Set API keys
export AIDP_CLAUDE_API_KEY="your-claude-api-key"
export AIDP_GEMINI_API_KEY="your-gemini-api-key"

AIDP includes powerful Tree-sitter-based static analysis capabilities for code.

The Tree-sitter analysis requires the Tree-sitter system library and pre-compiled language parsers:

# Install Tree-sitter system library
# macOS
brew install tree-sitter

# Ubuntu/Debian
sudo apt-get install tree-sitter

# Or follow the ruby_tree_sitter README for other platforms
# https://github.com/Faveod/ruby-tree-sitter#installation

# Install Tree-sitter parsers
./install_tree_sitter_parsers.sh

The install_tree_sitter_parsers.sh script automatically downloads and installs pre-built Tree-sitter parsers:

# Make the script executable
chmod +x install_tree_sitter_parsers.sh

# Run the installation script
./install_tree_sitter_parsers.sh

The script will:

• Detect your OS and architecture (macOS ARM64, Linux x64, etc.)
• Download the appropriate parser bundle from Faveod/tree-sitter-parsers
• Extract parsers to .aidp/parsers/ directory
• Set up the TREE_SITTER_PARSERS environment variable

After running the installation script, make the environment variable permanent:

# Add to your shell profile (e.g., ~/.zshrc, ~/.bashrc)
echo 'export TREE_SITTER_PARSERS="$(pwd)/.aidp/parsers"' >> ~/.zshrc

# Reload your shell
source ~/.zshrc

The Tree-sitter analysis generates structured JSON files in .aidp/kb/:

• symbols.json - Classes, modules, methods, and their metadata
• imports.json - Require statements and dependencies
• calls.json - Method calls and invocation patterns
• metrics.json - Code complexity and size metrics
• seams.json - Integration points and dependency injection opportunities
• hotspots.json - Frequently changed code areas (based on git history)
• tests.json - Test coverage analysis
• cycles.json - Circular dependency detection

The Tree-sitter analysis specifically supports:

• Seam Detection: Identifies I/O operations, global state access, and constructor dependencies
• Change Hotspots: Uses git history to identify frequently modified code
• Dependency Analysis: Maps import relationships and call graphs
• Test Coverage: Identifies untested public APIs
• Refactoring Opportunities: Suggests dependency injection points and seam locations

At gate steps, the AI creates files for interaction instead of requiring real-time chat:

• Questions files: PRD_QUESTIONS.md, ARCH_QUESTIONS.md, TASKS_QUESTIONS.md, IMPL_QUESTIONS.md - Contains questions if AI needs more information
• Output files: docs/PRD.md, docs/Architecture.md - Review and edit as needed
• Progress tracking: .aidp-progress.yml - Tracks completion status

When the AI creates a questions file, follow these steps:

1. Edit the file directly: Add your answers below each question in the file
2. Re-run the step: The AI will read your answers and complete the step
3. Approve when satisfied: Mark the step complete and continue

The questions file is only created when the AI needs additional information beyond what it can infer from your project structure and existing files. Your answers are preserved for future reference.

# Enable debug output to see AI provider communication
AIDP_DEBUG=1 aidp

# Log to a file for debugging
AIDP_LOG_FILE=aidp.log aidp

# Combine both for full debugging
AIDP_DEBUG=1 AIDP_LOG_FILE=aidp.log aidp

# Install dependencies
bundle install

# Install Tree-sitter parsers for development
./install_tree_sitter_parsers.sh

# Set up environment variables
export TREE_SITTER_PARSERS="$(pwd)/.aidp/parsers"

# Run tests
bundle exec rspec

# Run Tree-sitter analysis tests specifically
bundle exec rspec spec/aidp/analysis/
bundle exec rspec spec/integration/tree_sitter_analysis_workflow_spec.rb

# Run linter
bundle exec standardrb

# Auto-fix linting issues
bundle exec standardrb --fix

# Build gem
bundle exec rake build

The following system dependencies are required for development:

• Tree-sitter - System library for parsing (install via brew install tree-sitter or package manager)
• Ruby gems - All required gems are specified in aidp.gemspec and installed via bundle install

See CONTRIBUTING.md for development setup and conventional commit guidelines.

For detailed information:

• TUI User Guide - Complete guide to using the enhanced TUI
• Configuration Guide - Detailed configuration options and examples
• Troubleshooting Guide - Common issues and solutions

The gem packages markdown prompts that can also be used directly with Cursor or any LLM. See the templates/ directory for the individual prompt files that can be run manually.