# CodePilot

> [!WARNING]
> **Work in Progress (WIP)**: This project is under active development. Some components and agents are currently being optimized and refined.

CodePilot is a production-grade, autonomous AI software engineer and Model Context Protocol (MCP) server. It leverages **LangGraph** for task planning and execution, and uses a **hybrid RAG index** (combining **SQLite** for relational symbol mapping and **ChromaDB** for semantic code search) to edit, test, and debug codebases autonomously.

---

## 🏗️ System Architecture

CodePilot decouples the **Editor UI/Extension** from the **AI Agent Runtime** using the MCP protocol.

```text
       VS Code / Client (e.g. Cursor, Cline, Roo Code)
                             │
                             │ MCP (stdio)
                             ▼
                     FastMCP Server (Python)
                             │
                             ▼
                    LangGraph Supervisor
                             │
     Planner ──► Task Scheduler (Conditional Routing)
                             │
     ┌───────────────┬───────┴───────┬───────────────┐
     ▼               ▼               ▼               ▼
 Retriever       Coder Agent     Tester Node     Reflection
     │               │               │               │
     ▼               ▼               ▼               ▼
 SQLite / Chroma  Reviewer Gate   Test Runner     Git Safety Commit
                     │
                     ▼
              Patch Generator (Search/Replace Matcher)
```

---

## ⚡ Prerequisites

To run CodePilot locally, ensure the following are installed:
1. **Python >= 3.10**
2. **Git**
3. **Ollama** (for local offline LLM execution):
   * Download and run [Ollama](https://ollama.com/)
   * Pull the chat and embedding models in your terminal:
     ```bash
     ollama pull qwen2.5-coder:1.5b
     ollama pull nomic-embed-text
     ```

---

## 📦 Installation & Setup

1. **Activate the Conda Environment**:
   ```bash
   conda activate codepilot
   ```

2. **Install CodePilot in Editable Mode**:
   ```bash
   python -m pip install -e .
   ```

3. **Configure Environment Variables (Optional)**:
   Create a `.env` file in the root directory:
   ```env
   LLM_PROVIDER=ollama
   LLM_MODEL=qwen2.5-coder:1.5b
   OLLAMA_BASE_URL=http://localhost:11434
   ```

---

## 🧪 How to Verify and Run Tests

Run the full suite of unit tests to verify git safety tools, AST parser, indexers, scheduler graph routing, and FastMCP registration:

```bash
# Run all Phase 1-5 test suites
python -m unittest discover -s tests
```

To run a specific test suite directly:
```bash
# Test AST Parsers & DB RAG
python -m unittest tests/test_phase2.py

# Test LangGraph Compilation & Scheduler
python -m unittest tests/test_phase3.py

# Test FastMCP Server Registrations
python -m unittest tests/test_phase4.py
```

---

## 🚀 Usage Guide

### 1. Direct Execution via CLI
Use the command-line interface to execute the autonomous coding agent directly on a codebase:

```bash
python main.py --query "Your task description" --repo "path/to/target/repository" --max-iterations 3
```
* **`--query`**: The task you want the agent to accomplish (e.g. "Add JWT validation helper functions to auth.py").
* **`--repo`**: Absolute or relative path to the codebase repository you want CodePilot to index, modify, test, and commit.
* **`--max-iterations`**: The maximum number of self-healing compile/test debugging retries allowed before rolling back.

### 2. Stateful Interactive Shell Mode
Start CodePilot without a `--query` parameter to enter a stateful, interactive shell loop. The agent will greet you and keep track of modified files and conversation history across follow-up queries:

```bash
python main.py --repo "path/to/target/repository"
```


### 3. Integration via MCP Server (VS Code, Cursor, Claude)
Start the MCP server using:
```bash
python apps/mcp_server/server.py
```

To integrate CodePilot with client tools, register the Python script as an MCP server stdio transport in your settings.

#### Cursor Configuration
Add a new MCP server in Cursor settings (`Cursor Settings -> Features -> MCP`):
* **Name**: CodePilot
* **Type**: `stdio`
* **Command**: `conda run -n codepilot python "path/to/CodePilot/apps/mcp_server/server.py"`

#### Claude Desktop Configuration
Add the following to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "codepilot": {
      "command": "conda",
      "args": [
        "run",
        "-n",
        "codepilot",
        "python",
        "path/to/CodePilot/apps/mcp_server/server.py"
      ]
    }
  }
}
```

---

## ⚙️ Modular Safety Strategy
* **Git Safe Guarding**: Before applying any changes, CodePilot creates a temporary safety commit. If linter checks or pytest runs fail during verification, CodePilot automatically rolls back modifications, leaving your active workspace clean and untouched.
* **Fuzzy Matcher**: The patching agent writes exact Search/Replace blocks. If minor spacing or indentation variations exist in the files, CodePilot's fuzzy sliding-window matcher resolves them safely.
 
```
# Create a Tic-Tac-Toe game
python main.py --query "Create a Tic-Tac-Toe game in game.py with a simple text UI" --repo projects/tictactoe

# Create a Flask app
python main.py --query "Create a Flask app in app.py with a /hello endpoint" --repo projects/flask_demo

# Add tests
python main.py --query "Create tests/test_calculator.py with pytest tests for add, subtract" --repo projects/codepilot_calc

# Interactive mode (type multiple queries)
python main.py --repo projects/codepilot_calc
```