aide-cli/README.md

AIDE - The companion control system for Claude Code with intelligent task management

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

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

```bash
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

```bash
# 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)
```bash
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
```bash
# 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:**
```bash
# 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:**
```bash
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:**
```bash
# 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:

```bash
# 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
```bash
# 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**
```bash
# 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?**
```bash
# Install Python 3.7+, then:
aide install --python python3
```

**Permission errors?**
```bash
# 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?**
```bash
# 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?**
```bash
# Restart daemon
aide-daemon stop
aide-daemon start

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

**Port 47742 already in use?**
```bash
# Check what's using the port
lsof -i :47742

# Stop AIDE daemon
aide-daemon stop

# Kill any conflicting process if needed
```

**Authentication token issues?**
```bash
# 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

```bash
# 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**: acevedo.eduardo@outlook.com

## 📄 License

MIT License - see LICENSE file for details.

## 🙏 Acknowledgments

- Built for the [Claude Code](https://docs.anthropic.com/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?**

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

# Run installation
aide install
```

*Transform interruptions from frustrations into intelligent adaptations.*