CodePilot 🚀

CodePilot is a highly capable, autonomous AI software engineer command-line interface (CLI). Built using Pydantic AI and powered by Groq's lightning-fast LPU inference engine, CodePilot can write, test, debug, and refactor code in any programming language (Python, C++, JS, Bash, etc.) directly within your workspace directory.

---

🛠️ Key Features

1. Multi-Language Engineering: Handles Python, C++, JavaScript, and Bash tasks natively. It leverages a python runner harness to compile, execute, and assert code logic in compiled languages like C++.
2. Self-Healing Imports (Automatic Dependency Resolution): If a Python script fails due to a missing third-party package (ModuleNotFoundError), CodePilot parses standard error, dynamically installs the dependency using uv (or pip), and automatically retries execution.
3. Secure Workspace Integration: Reads, writes, and lists files inside your workspace with built-in path-traversal safeguards, transitioning from a simple snippet execution tool to a full-fledged multi-file software engineering assistant.
4. Rich Terminal UI: Offers premium user experience with status spinners, syntax-highlighted solutions, clear markdown explanations, and color-coded status panels.

---

📂 Project Structure

code-pilot/
├── main.py             # CLI Entrypoint & CLI Output Styling
├── pyproject.toml      # Dependency & Package configurations
├── .env                # API Key and Model configuration
└── src/
    ├── agent.py        # Pydantic AI Agent setup & tool registration
    ├── schema.py       # Data validation models (Pydantic/Dataclass)
    ├── prompt.py       # Generalized multi-language system prompt
    ├── tools.py        # Workspace & Execution tool implementations
    ├── executor.py     # Python subprocess sandboxing & self-healing logic
    └── config.py       # System settings & environment loaders

---

📚 Libraries Used & Their Roles

CodePilot's architecture relies on several cutting-edge libraries:

1. pydantic-ai

• What it is: An agentic framework built on top of Pydantic for writing production-grade AI agents.
• Role in CodePilot: Orchestrates the agent lifecycle, handles structured inputs and output schema validation, manages context dependencies (Deps), and registers function-based tools seamlessly using python decorators.

2. groq

• What it is: An SDK for interacting with Groq's high-speed inference engine.
• Role in CodePilot: Provides access to advanced Large Language Models (e.g., llama-3.3-70b-versatile) with sub-second token latency, allowing fast and efficient multi-turn engineering reasoning.

3. rich

• What it is: A Python library for rich text and beautiful formatting in terminal interfaces.
• Role in CodePilot: Generates the interactive command-line interface, providing clear panels, code syntax highlighting (matching the language returned by the LLM), markdown formatting, and loading spinners.

4. typer

• What it is: A library for building CLI applications based on Python type hints.
• Role in CodePilot: Manages command execution, handles argument validation, and automatically creates standard shell helper screens.

5. python-dotenv

• What it is: A configuration loader that reads key-value pairs from a .env file.
• Role in CodePilot: Safely loads the GROQ_API_KEY and model configuration without hardcoding secrets in the repository.

---

⚙️ Architecture & Code Flow

graph TD
    User([User Prompt]) --> CLI[main.py CLI Orchestrator]
    CLI --> Agent[src/agent.py CodePilotAgent]
    Agent --> Tools[src/tools.py Tool Registry]
    
    subgraph Sandbox Environment
        Tools --> Exec[src/executor.py Sandboxed Execution]
        Exec --> SelfHealing[Dependency Installer uv/pip]
    end
    
    subgraph Workspace File System
        Tools --> Read[read_workspace_file]
        Tools --> Write[write_workspace_file]
        Tools --> List[list_workspace_directory]
    end
    
    Exec -.-> |Returns Output/Errors| Agent
    Read -.-> |Returns Contents| Agent
    Write -.-> |Returns Success| Agent
    List -.-> |Returns Structure| Agent
    
    Agent --> Schema[src/schema.py validation]
    Schema --> Output[FinalCode Output]
    Output --> CLI
    CLI --> Screen([Rich Terminal Display])

Loading

---

🧪 How It Works Under the Hood

Self-Healing Imports Example

When the agent executes a script that imports a library not currently installed (e.g. import requests):

1. Execution Failure: The code runs via a subprocess in a temporary directory and fails with: ModuleNotFoundError: No module named 'requests'
2. Detection: src/executor.py captures the standard error, parses it using regular expressions, and extracts the missing module name (requests).
3. Installation: CodePilot runs uv pip install requests (falling back to standard pip if uv is unavailable) to install the package in the environment.
4. Auto-Retry: The code is instantly executed again. On the second try, it runs successfully and returns the output to the agent.

---

🚀 Getting Started

Prerequisites

• Python 3.11 or newer
• uv (recommended) or standard pip
• A Groq API Key

Installation & Setup

1. Clone or copy the repository contents.
2. In the project root, create a .env file containing your Groq credentials:

   GROQ_API_KEY=your_groq_api_key_here
   GROQ_MODEL=llama-3.3-70b-versatile

3. Install dependencies:

   uv sync
   # OR
   pip install -r pyproject.toml

Running Tasks

To execute a task, run main.py and supply a prompt:

# Using uv (recommended)
uv run python main.py "your task description"

# Or using the virtual environment python interpreter directly
.venv/Scripts/python main.py "your task description"

If you do not provide a task description as an argument, CodePilot will interactively prompt you for one.

---

📝 Example Executions

Example 1: Solving a Python Task with External Dependencies

Prompt:

"Fetch the current price of Bitcoin in USD from the CoinGecko public API, print it out nicely, and return the Python script."

Agent Trace:

1. CodePilot receives the task and identifies Python as the language.
2. It writes a test script that imports requests to fetch price details.
3. The sandbox runs the script. If requests is missing:
   • A ModuleNotFoundError is caught.
   • CodePilot prints: Dependency 'requests' is missing. Attempting automatic installation...
   • It runs uv pip install requests automatically.
   • The test script is re-run and succeeds, outputting: Bitcoin: $X,XXX.XX
4. The CLI shows the final Python script with syntax highlighting and a summary.

---

Example 2: Engineering a Workspace-Level C++ Component

Prompt:

"Write a C++ class 'MyVector' (without ) that supports push_back, pop_back, size, capacity, and operator[]. Write a C++ test suite with assertions, compile it with g++, and verify it runs successfully."

Agent Trace:

1. CodePilot understands it needs to write C++ code.
2. The agent calls the write_workspace_file tool to save MyVector.h and main.cpp directly in the project workspace.
3. It constructs a short Python driver to execute in run_Python:

   import subprocess
   # Compile using local g++ toolchain
   compilation = subprocess.run(["g++", "-std=c++11", "main.cpp", "-o", "test_vector"], capture_output=True, text=True)
   if compilation.returncode != 0:
       print("Compilation failed:", compilation.stderr)
       exit(1)
   
   # Run the resulting test binary
   run = subprocess.run(["./test_vector"], capture_output=True, text=True)
   print(run.stdout)
   print(run.stderr)
   exit(run.returncode)

4. Pydantic AI captures Result: [SUCCESS] indicating that the compiled binary executed and the assertions passed.
5. CodePilot responds with the verified C++ code inside the FinalCode block, and the CLI prints a beautiful final summary.