CodePilot

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.

       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)

Related MCP server: Gravitas-Core-MCP

⚡ 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

   • Pull the chat and embedding models in your terminal:

     ollama pull qwen2.5-coder:1.5b
     ollama pull nomic-embed-text

📦 Installation & Setup

1. Activate the Conda Environment:

   conda activate codepilot

2. Install CodePilot in Editable Mode:

   python -m pip install -e .

3. Configure Environment Variables (Optional): Create a .env file in the root directory:

   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:

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

To run a specific test suite directly:

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

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:

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

3. Integration via MCP Server (VS Code, Cursor, Claude)

Start the MCP server using:

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:

{
  "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