🎯 AIDE - Adaptive Intelligent Development Enhancer

Unlock the Full Potential of Claude Code with Advanced Project Memory & Planning

AIDE is a specialized tool designed to supercharge your Claude Code experience. We don't compete with Claude Code - we amplify it by adding persistent memory, intelligent planning, and adaptive project management that Claude Code currently lacks.

Transform Claude Code into an adaptive AI assistant that learns from your patterns, handles interruptions intelligently, and maintains persistent context across sessions.

⚡ Quick Start

# Step 1: Install AIDE globally
npm install -g aide-cli@latest

# Step 2: Run the installation command
aide install

⚠️ IMPORTANT: Do NOT use npx - It has known issues with hanging and incomplete installations. Always use the two-step npm installation process above.

That's it! AIDE installs with daemon mode enabled by default for seamless command execution. Open Claude Code and start working - AIDE will activate automatically.

🚀 What is AIDE?

AIDE is the companion control system for Claude Code that manages every aspect of your development workflow:

🎯 Central Task Control

• Controls ALL Actions: Every file edit, command, and code generation goes through AIDE
• Automatic Task Management: Creates, tracks, and completes tasks automatically
• Intelligent Feedback Loop: Learns from every action to improve future suggestions
• Context Preservation: Maintains complete project state across sessions

🤝 How AIDE Works as Claude's Companion

• Pre-processes every action before execution
• Tracks all tasks and subtasks automatically
• Provides real-time context to Claude
• Manages interruptions and priority changes
• Learns from your patterns to optimize workflow

🔗 Perfect Companion to Claude Code

• ✅ Works WITH Claude Code - not against it
• ✅ Enhances Claude's capabilities with persistent memory
• ✅ Adds intelligent project planning to any Claude session
• ✅ Preserves context between Claude Code sessions
• ✅ Complements Claude's natural language understanding

🎆 Key Features

Task Control System:

• 📝 Automatic Task Creation: Detects when tasks are needed from user input
• 📋 Task Hierarchy: Manages tasks, subtasks, and dependencies
• 🔄 Pre-Task Processing: Analyzes every action before execution
• 📊 Progress Tracking: Real-time progress with completion rates

Intelligence Features:

• 🧠 Persistent Memory: Remembers all decisions and patterns
• 🔄 Smart Adaptation: 4 strategies for handling interruptions
• 🎯 Pattern Learning: Improves suggestions based on your habits
• 📸 Context Snapshots: Branch and resume work anytime
• 🔮 Confidence Scoring: Shows certainty for each decision

Advanced Capabilities:

• 🤖 ML Analysis: Complexity prediction and optimization
• ⚡ Performance Insights: Project performance analysis
• ⏱️ Time Estimation: Predictive timeline generation
• 👥 Collaboration: Team features and sharing

🆚 AIDE vs Regular Claude Code

| Feature | Regular Claude Code | AIDE Enhanced | |---------|-------------------|------------------| | Memory | Session only | Persistent across sessions | | Interruptions | Basic response | 4 intelligent strategies | | Progress | Estimates | Real calculation | | Adaptation | Manual | Automatic detection | | Context | Lost on restart | Preserved via snapshots | | Learning | None | Learns user patterns |

🚀 How It Works

Automatic Activation

AIDE activates automatically when you start working:

You: "Create a React dashboard with analytics"
Claude: [AIDE initializes] → [Sets objective] → [Tracks progress]

Intelligent Interruption Handling

AIDE detects when you change direction:

You: "Actually, add authentication first"
Claude: 🔄 AIDE: Detected requirement change
       Current progress: 30% on dashboard
       Strategy: MERGE - integrate auth while building dashboard

Smart Strategies

1. MERGE - Integrate changes without losing progress
2. BRANCH - Save state, handle urgent task, resume later
3. REPLAN - Create new plan incorporating changes
4. DEFER - Complete current task first, then address request

🎯 How AIDE Controls Claude Code

Task Control Flow

1. User Request → AIDE analyzes and creates task
2. Claude Action → AIDE pre-processes and tracks
3. Execution → AIDE monitors and provides feedback
4. Completion → AIDE updates progress and learns

Example Workflow

User: "Create a REST API for user management"

Claude (internally):
1. aide-task add "Create REST API for user management" high
2. aide-task start <task_id>
3. aide-pre-task file create "app.py"  # Before creating file
4. aide-pre-task code "FastAPI user routes" python  # Before writing code
5. aide-task complete <task_id> "Basic API structure created"

Continuous Feedback

• AIDE tracks EVERY action Claude takes
• Builds a complete history of decisions
• Learns patterns to improve future suggestions
• Provides context for better decision making

⚡ Critical Auto-Execution Rules

IMPORTANT: After installation, Claude Code will automatically follow these mandatory rules:

🤖 Automatic AIDE Behavior

Claude Code will automatically execute these commands without asking permission:

1. 🔍 Auto-Detection: Always checks ls -la .aide/ before starting any work
2. 🚀 Auto-Initialize: If .aide/ missing, immediately runs aide-init
3. 🎯 Auto-Track: When you give an objective, immediately runs aide-track "your objective"
4. 📊 Auto-Status: Shows intelligent progress with aide-status
5. 🔄 Auto-Adapt: When you change direction, immediately runs aide-adapt "your change"

🚨 Critical: These Are NOT Suggestions

• ❌ Claude Code will NOT ask permission to run AIDE commands
• ❌ Claude Code will NOT suggest running them manually
• ❌ Claude Code will NOT use wrapper scripts
• ✅ Claude Code will AUTOMATICALLY EXECUTE daemon commands
• ✅ Commands run instantly: aide-init, aide-track, aide-status, aide-adapt

📝 Example Auto-Execution

You: "Help me build a FastAPI application"
Claude Code: [runs ls -la .aide/] → [runs aide-init] → [runs aide-track "build FastAPI application"] 
Claude Code: [runs aide-status] Shows progress and begins work

You: "Actually, add authentication first"
Claude Code: [runs aide-adapt "add authentication first"] → Shows strategy and adapts

This behavior is built into CLAUDE.md and ensures AIDE works seamlessly without interruption.

📋 Commands

# After npm installation, run this to configure Claude Code
aide install

# Install without daemon (direct Python execution)
aide install --no-daemon

# Explicitly enable daemon mode
aide install --daemon

# Verify installation
aide verify

# Show current project status  
aide status

# Uninstall (keeps backups)
aide uninstall

# Force reinstall
aide install --force

# Use specific Python version
aide install --python python3.11

# Daemon control commands (when daemon mode is enabled)
aide-daemon start    # Start AIDE daemon
aide-daemon stop     # Stop AIDE daemon  
aide-daemon status   # Check daemon status

# Task management commands (NEW in v2.1.0)
aide-task            # Show current task status
aide-task add "<description>" [priority]  # Add new task
aide-task start <task_id>     # Start working on task
aide-task complete <task_id>  # Mark task as complete
aide-task status             # Show all tasks

# Pre-task processing (used internally by Claude)
aide-pre-task file <operation> <path>  # Before file operations
aide-pre-task command <cmd> <args>     # Before command execution
aide-pre-task code "<desc>" <language> # Before code generation

🔧 Installation Options

Default Installation (Recommended)

aide install  # Enables daemon mode by default

Automatic Detection

AIDE automatically finds and configures:

• Python 3.7+ installation
• Claude Code directory
• Platform-specific settings
• Daemon mode enabled for seamless execution

Manual Configuration

# Specify Python command
aide install --python python3.11

# Specify Claude directory
aide install --claude-dir ~/.claude

# Force reinstall over existing
aide install --force

# Disable daemon mode (maximum security)
aide install --no-daemon

🤖 Daemon Mode vs Direct Mode

AIDE offers two execution modes to fit different user preferences and security requirements.

🚀 Daemon Mode (Default & Recommended)

Benefits:

• ✅ Seamless execution - No permission prompts for each command
• ✅ Faster response - Commands execute instantly through background daemon
• ✅ Automatic startup - Daemon starts automatically when needed
• ✅ Secure - Local-only daemon (localhost:47742) with token authentication
• ✅ Fallback protection - Falls back to direct execution if daemon fails

How it works:

# Install with daemon mode (default)
aide install

# Claude can now run commands seamlessly:
You: "Create a React dashboard"
Claude: [runs aide-init] → [runs aide-track "React dashboard"] → starts work
# No permission prompts! 🎉

Daemon Management:

aide-daemon start    # Start daemon manually
aide-daemon stop     # Stop daemon  
aide-daemon status   # Check if running

🔒 Direct Mode (Maximum Security)

Benefits:

• ✅ Full control - You approve every Python script execution
• ✅ Maximum security - No background processes
• ✅ Transparent - See exactly what commands run
• ✅ Simple - Direct Python script execution

How it works:

# Install without daemon
aide install --no-daemon

# Claude runs commands directly (with your approval):
You: "Create a React dashboard"  
Claude: [requests to run python3 aide_init.py] 
You: [approve] ✅
Claude: [requests to run python3 aide_track.py "React dashboard"]
You: [approve] ✅

🎛️ Choosing Your Mode

Choose Daemon Mode if:

• You trust AIDE and want seamless operation
• You work on multiple projects frequently
• You prefer minimal interruptions
• You're comfortable with local background services

Choose Direct Mode if:

• You prefer maximum control over script execution
• You work in high-security environments
• You want to inspect every command before execution
• You prefer explicit approval for automation

🔄 Switching Between Modes

You can change modes anytime by reinstalling:

# Switch to daemon mode (or reinstall default)
aide install --force

# Switch to direct mode  
aide install --no-daemon --force

🎮 Usage Examples

Starting a New Project

You: "Build a FastAPI for user management"
Claude: [AIDE auto-initializes]
        🎯 Objective: FastAPI user management system
        📊 Progress: 0% (Analysis phase)
        🚀 Starting implementation...

Handling Interruptions

You: "Wait, I need Docker support too"
Claude: 🔄 AIDE Adaptation Analysis
        📝 Request: Docker support addition
        🔍 Type: clarification (priority: medium)
        📊 Current: 40% on API endpoints
        🎯 Strategy: MERGE
        💡 Plan: Add Dockerfile while continuing API development

Checking Progress

You: "How are we doing?"
Claude: 🎯 AIDE Status Report
        📋 Objective: FastAPI user management + Docker
        📊 Progress: 75% (6/8 tasks completed)
        🔄 Adaptations: 2 handled successfully
        🧠 Pattern: User prefers comprehensive solutions
        💡 Next: Testing and documentation

🎯 Benefits in Action

Memory Across Sessions

Day 1: Work on API, implement auth
Day 2: Claude remembers auth decisions, builds on previous work
Day 3: Continues with same patterns and context

Pattern Learning

After 3 projects, AIDE learns:
- You prefer TypeScript over JavaScript
- You always add Docker later in projects  
- You like comprehensive error handling

Smart Snapshots

You: "Emergency bug fix needed"
Claude: 🔄 AIDE: Creating snapshot "dashboard-work"
        🎯 Switching to bug fix mode
        💾 Can resume dashboard work exactly where left off

🔐 Privacy & Security

IMPORTANT: AIDE runs completely offline and respects your privacy.

What AIDE Does NOT Send:

• ❌ Your source code
• ❌ Project files or content
• ❌ Personal information
• ❌ Claude conversations
• ❌ Any sensitive data

AIDE operates entirely on your local machine. No external connections or data transmission.

🛠️ Requirements

• Node.js 14+ (for installation)
• Python 3.7+ (any variant: python3, python, py)
• Claude Code (official Anthropic CLI)

🔧 Troubleshooting

Installation Issues

# Check system compatibility
aide verify

# Force clean install
aide uninstall
aide install --force

# Use specific Python
aide install --python /usr/local/bin/python3.11

Common Problems

🚫 DO NOT USE NPX

# WRONG - This causes hanging and installation issues
npx aide-cli install  # ❌ DO NOT USE

# CORRECT - Always use the two-step process
npm install -g aide-cli@latest  # ✅ Step 1
aide install                    # ✅ Step 2

Python not found?

# Install Python 3.7+, then:
aide install --python python3

Permission errors?

# On macOS/Linux:
sudo aide install

# Or install to user directory:
aide install --claude-dir ~/my-claude

Claude Code not working?

• Ensure Claude Code is properly installed
• Check ~/.claude/CLAUDE.md exists after installation
• Try opening a new Claude Code session

Daemon Mode Issues

Daemon not starting?

# Check if daemon is running
aide-daemon status

# Start daemon manually
aide-daemon start

# Check daemon logs
cat ~/.claude/.aide-daemon/daemon.log

Commands hanging or slow?

# Restart daemon
aide-daemon stop
aide-daemon start

# Or switch to direct mode temporarily
aide install --no-daemon --force

Port 47742 already in use?

# Check what's using the port
lsof -i :47742

# Stop AIDE daemon
aide-daemon stop

# Kill any conflicting process if needed

Authentication token issues?

# Reset daemon authentication
aide-daemon stop
rm ~/.claude/.aide-daemon/daemon-token
aide-daemon start

🏗️ Architecture

Core Components

AIDE Package
├── 🔍 Python Detector (finds best Python)
├── 🔧 Cross-platform Installer  
├── 📜 Dynamic Wrapper Scripts
├── 🧠 Persistent Memory System
├── 🔄 Adaptation Engine
├── 🤖 Local Daemon (optional)
└── ✅ Installation Verifier

Execution Modes

Daemon Mode Architecture:

Claude Code → aide-init → Local Daemon (port 47742) → Python Scripts → Response
              ↓
         Auto-startup if needed
              ↓  
         Token authentication
              ↓
         Secure execution

Direct Mode Architecture:

Claude Code → python3 script.py → User Approval → Python Scripts → Response
              ↓
         Manual approval each time
              ↓
         Maximum transparency

📊 System Files Created

Common Files (Both Modes)

~/.claude/
├── CLAUDE.md              # Enhanced with AIDE integration
├── aide_init.py           # Initialization script
├── aide_track.py          # Objective tracking  
├── aide_status.py         # Status display
├── aide_adapt.py          # Interruption handling
├── aide-wrapper.sh        # Unix wrapper (or .bat for Windows)
└── backups/               # CLAUDE.md backups
    └── CLAUDE-2024-01-15.md

Additional Files (Daemon Mode Only)

~/.claude/
├── .aide-daemon/          # Daemon configuration
│   ├── daemon-token       # Secure authentication token
│   ├── daemon.pid         # Process ID file
│   └── daemon.log         # Daemon activity log
└── aide-daemon            # Daemon control script

Project Files (Auto-created)

your-project/
└── .aide/
    ├── plan.json          # Objectives and task graph
    ├── context.json       # Session and project context
    ├── memory.log         # Decision history
    └── snapshots/         # State snapshots for branching
        └── snapshot_123.json

🔄 Upgrade & Updates

# Update to latest version
npm update -g aide-cli

# Reinstall with new features
aide install --force

# Check version
aide --version

💡 Tips & Best Practices

General Usage

1. Be specific with objectives - "Build user auth" vs "Create complete FastAPI authentication system with JWT, password reset, and role management"

2. Let AIDE handle interruptions - Don't restart from scratch, let AIDE adapt your current work

3. Check status regularly - Use aide status to see progress and suggestions

4. Trust the strategies - AIDE's suggestions are based on context analysis and historical patterns

5. Review memory logs - Check .aide/memory.log to understand decision patterns

Daemon Mode Tips

6. Use daemon mode for frequent work - If you work with Claude Code regularly, daemon mode eliminates friction

7. Monitor daemon health - Occasionally run aide-daemon status to ensure smooth operation

8. Restart daemon if issues - If commands feel slow, restart with aide-daemon stop && aide-daemon start

Direct Mode Tips

9. Approve selectively - In direct mode, you can skip non-critical commands if needed

10. Review commands before approval - Take advantage of the transparency to understand AIDE's actions

🤝 Contributing & Support

AIDE is open source! Contributions welcome:

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features and improvements
• 🔧 Submit pull requests
• 📖 Improve documentation
• 📧 Contact & Support: [email protected]

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built for the Claude Code ecosystem
• Inspired by adaptive planning systems and cognitive architectures
• Created by the community, for the community

Ready to supercharge your Claude Code experience?

# Install AIDE globally
npm install -g aide-cli@latest

# Run installation
aide install

Transform interruptions from frustrations into intelligent adaptations.