Initial CodePilot deployment - Multi-agent AI coding assistant

.dockerignore

@@ -0,0 +1,46 @@
+# Virtual environment
+venv/
+.venv/
+env/
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Environment files (secrets)
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Cache directories
+.codepilot_cache/
+.cache/
+.chroma/
+
+# Test files
+tests/
+test_*.py
+*_test.py
+
+# Documentation (not needed in container)
+*.md
+!README.md
+docs/
+
+# Misc
+*.log
+*.tmp
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,39 @@
+# HuggingFace Spaces Dockerfile for CodePilot
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install git (needed for cloning repos) and other system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user for security (HF Spaces requirement)
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Set working directory for user
+WORKDIR $HOME/app
+
+# Copy requirements first (for better caching)
+COPY --chown=user requirements-cloud.txt ./requirements.txt
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY --chown=user . .
+
+# Expose port 7860 (HuggingFace Spaces default)
+EXPOSE 7860
+
+# Set environment variables
+ENV PORT=7860
+ENV HOST=0.0.0.0
+
+# Run Chainlit
+CMD ["chainlit", "run", "chainlit_app.py", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,73 @@
 ---
-title: Codepilot
-emoji: 🐨
-colorFrom: yellow
-colorTo: gray
+title: CodePilot
+emoji: "\U0001F916"
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# CodePilot - AI Coding Assistant
+
+**Multi-agent AI system that plans, writes, tests, and reviews code autonomously**
+
+## What Makes This Different
+
+| Feature | CodePilot | GitHub Copilot | Cursor |
+|---------|-----------|----------------|--------|
+| Multi-agent workflow | Planner > Coder > Reviewer | Single agent | Single agent |
+| Sandboxed execution | Code tested before presenting | No | No |
+| Codebase understanding | Hybrid search (BM25 + semantic) | Limited | Good |
+| Quality report | Confidence, security, complexity | No | No |
+
+## How It Works
+
+```
+User Request
+     |
+     v
++---------------------------------------+
+|           ORCHESTRATOR                |
+|  +--------+  +--------+  +--------+   |
+|  |Planner |->| Coder  |->|Reviewer|   |
+|  +--------+  +--------+  +--------+   |
++---------------------------------------+
+     |              |
+     v              v
++---------+   +----------+
+| Context |   |   E2B    |
+| Engine  |   | Sandbox  |
++---------+   +----------+
+```
+
+1. **Planner Agent** - Searches codebase, understands context, creates implementation plan
+2. **Coder Agent** - Writes code, uploads to sandbox, runs tests iteratively
+3. **Reviewer Agent** - Reviews tested code, approves or requests changes
+
+## Features
+
+- **Autonomous coding** - Give it a task, it figures out the rest
+- **Sandboxed execution** - Code runs in isolated E2B containers
+- **Multi-agent architecture** - Specialized agents for planning, coding, reviewing
+- **Codebase search** - Hybrid retrieval with BM25 + semantic search
+- **Real-time feedback** - See what each agent is doing as it works
+
+## Tech Stack
+
+- **Python** - Core language
+- **OpenAI GPT-4** - LLM for agent reasoning
+- **LangChain/LangGraph** - Agent orchestration
+- **E2B** - Sandboxed code execution
+- **Chainlit** - Chat UI
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY` | Your OpenAI API key |
+| `E2B_API_KEY` | Your E2B sandbox API key |
+
+## License
+
+MIT

chainlit.md

@@ -0,0 +1,14 @@
+# Welcome to Chainlit! 🚀🤖
+
+Hi there, Developer! 👋 We're excited to have you on board. Chainlit is a powerful tool designed to help you prototype, debug and share applications built on top of LLMs.
+
+## Useful Links 🔗
+
+- **Documentation:** Get started with our comprehensive [Chainlit Documentation](https://docs.chainlit.io) 📚
+- **Discord Community:** Join our friendly [Chainlit Discord](https://discord.gg/k73SQ3FyUh) to ask questions, share your projects, and connect with other developers! 💬
+
+We can't wait to see what you create with Chainlit! Happy coding! 💻😊
+
+## Welcome screen
+
+To modify the welcome screen, edit the `chainlit.md` file at the root of your project. If you do not want a welcome screen, just leave this file empty.

chainlit_app.py

@@ -0,0 +1,346 @@
+"""
+Chainlit UI for CodePilot Multi-Agent System
+
+This provides a chat interface showing detailed agent workflow:
+- Planner creates implementation plans
+- Coder writes code, uploads to sandbox, runs tests
+- Reviewer checks and approves code
+
+User can see every step in real-time.
+"""
+
+import chainlit as cl
+import os
+import sys
+import io
+from contextlib import redirect_stdout, redirect_stderr
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+
+# Check if running in production BEFORE importing heavy dependencies
+# Detects: Render, HuggingFace Spaces, or any cloud with PORT env var
+IS_PRODUCTION = os.getenv('RENDER_SERVICE_NAME') or os.getenv('RENDER') or os.getenv('SPACE_ID') or os.getenv('PORT')
+
+# Only import heavy ML dependencies in local development
+if not IS_PRODUCTION:
+    from codepilot.tools.context_tools import index_codebase
+
+# Import orchestrator (lighter weight)
+from codepilot.agents.orchestrator import Orchestrator
+
+
+# Authentication disabled for now - uncomment to enable password protection
+# @cl.password_auth_callback
+# def auth_callback(username: str, password: str):
+#     """
+#     Simple password authentication for CodePilot.
+#
+#     For production, use environment variables and proper password hashing.
+#     """
+#     # Get password from environment variable (more secure)
+#     required_password = os.getenv('CHAINLIT_PASSWORD', 'codepilot2024')
+#
+#     # In production, you should hash passwords and use a proper auth system
+#     if password == required_password:
+#         return cl.User(
+#             identifier=username,
+#             metadata={"role": "user", "provider": "credentials"}
+#         )
+#     return None
+
+
+@cl.on_chat_start
+async def start():
+    """Initialize the agent system when chat starts."""
+
+    print("[CHAINLIT] on_chat_start triggered")  # Debug log
+
+    await cl.Message(
+        content="# 🤖 CodePilot - Autonomous AI Coding Agent\n\n"
+                "I can help you write code, fix bugs, and implement features!\n\n"
+                "**How it works:**\n"
+                "1. 🤔 **Planner** - Searches codebase and creates implementation plan\n"
+                "2. 💻 **Coder** - Writes code locally, uploads to sandbox, runs tests\n"
+                "3. 👁️ **Reviewer** - Reviews tested code and decides approval\n\n"
+                "**What I can do:**\n"
+                "- Write new functions and features\n"
+                "- Fix bugs and add error handling\n"
+                "- Create tests and verify code works\n"
+                "- Search and understand your codebase\n\n"
+                "**Ready!** What would you like me to build?"
+    ).send()
+
+    print("[CHAINLIT] Welcome message sent")  # Debug log
+
+    # Skip indexing on deployment to avoid startup issues (using module-level constant)
+    if IS_PRODUCTION:
+        print(f"[CHAINLIT] Running in production mode (PORT={os.getenv('PORT')}) - skipping codebase indexing")
+        await cl.Message(content="ℹ️ Running in cloud mode - codebase indexing disabled").send()
+        cl.user_session.set("orchestrator", Orchestrator(max_iterations=3))
+        cl.user_session.set("ready", True)
+        print("[CHAINLIT] Orchestrator created, ready=True")
+        return
+
+    # Index codebase in background (only in local development)
+    index_msg = await cl.Message(content="🔍 Indexing codebase...").send()
+
+    try:
+        # Get project root
+        project_root = os.path.dirname(os.path.abspath(__file__))
+        index_result = index_codebase(project_root)
+
+        # Update message content
+        index_msg.content = f"✅ Codebase indexed!\n```\n{index_result}\n```"
+        await index_msg.update()
+
+        # Store orchestrator in session (reduced iterations to save API credits)
+        cl.user_session.set("orchestrator", Orchestrator(max_iterations=3))
+        cl.user_session.set("ready", True)
+
+    except Exception as e:
+        # Update message content
+        index_msg.content = f"⚠️ Indexing failed (will continue anyway):\n```\n{str(e)}\n```"
+        await index_msg.update()
+        # Still create orchestrator even if indexing fails
+        cl.user_session.set("orchestrator", Orchestrator(max_iterations=10))
+        cl.user_session.set("ready", True)
+
+
+@cl.on_message
+async def main(message: cl.Message):
+    """Handle user messages and run the agent workflow."""
+
+    # Check if ready
+    if not cl.user_session.get("ready"):
+        await cl.Message(content="⚠️ System is still initializing, please wait...").send()
+        return
+
+    # Get orchestrator
+    orchestrator: Orchestrator = cl.user_session.get("orchestrator")
+
+    # Create a message for streaming logs
+    log_msg = cl.Message(content="")
+    await log_msg.send()
+
+    try:
+        # Capture stdout/stderr to stream logs
+        captured_output = io.StringIO()
+
+        def run_orchestrator():
+            """Run orchestrator in thread and capture output."""
+            try:
+                with redirect_stdout(captured_output), redirect_stderr(captured_output):
+                    return orchestrator.run(message.content)
+            except Exception as e:
+                # Capture any exceptions from orchestrator
+                print(f"❌ Error in orchestrator: {str(e)}")
+                import traceback
+                traceback.print_exc()
+                raise
+
+        # Run in thread pool to avoid blocking
+        loop = asyncio.get_event_loop()
+        executor = ThreadPoolExecutor(max_workers=1)
+
+        # Start the orchestrator in background
+        future = loop.run_in_executor(executor, run_orchestrator)
+
+        # Track API usage
+        total_prompt_tokens = 0
+        total_completion_tokens = 0
+        total_tokens = 0
+        seen_token_lines = set()  # Track which token lines we've already counted
+
+        # Stream logs while orchestrator is running - FILTERED
+        accumulated_logs = ""
+        while not future.done():
+            await asyncio.sleep(0.5)  # Check every 500ms
+
+            # Get new output
+            current_output = captured_output.getvalue()
+            if current_output != accumulated_logs:
+                accumulated_logs = current_output
+
+                # Filter logs to show only important lines
+                filtered_lines = []
+                for line in accumulated_logs.split('\n'):
+                    # Extract token usage before filtering (only count each line once!)
+                    if '📊 Tokens:' in line and line not in seen_token_lines:
+                        seen_token_lines.add(line)  # Mark as counted
+                        try:
+                            # Parse: "📊 Tokens: 505 prompt + 20 completion = 525 total"
+                            parts = line.split('Tokens:')[1].strip()
+                            prompt = int(parts.split('prompt')[0].strip())
+                            completion = int(parts.split('+')[1].split('completion')[0].strip())
+                            total_prompt_tokens += prompt
+                            total_completion_tokens += completion
+                            total_tokens += (prompt + completion)
+                        except:
+                            pass
+
+                    # Skip token counts, progress bars, and verbose details
+                    if any(skip in line for skip in ['📊 Tokens:', 'Batches:', '|##', 'it/s]']):
+                        continue
+                    # Keep important lines
+                    if any(keep in line for keep in [
+                        '[ORCHESTRATOR]', '[PLANNER]', '[CODER]', '[REVIEWER]',
+                        'Calling tool:', '✅ Tool', 'Transitioning', 'APPROVED', 'REJECTED'
+                    ]):
+                        filtered_lines.append(line)
+
+                filtered_output = '\n'.join(filtered_lines)
+
+                # Calculate cost (GPT-3.5-turbo pricing: $0.0015/1K input, $0.002/1K output)
+                input_cost = (total_prompt_tokens / 1000) * 0.0015
+                output_cost = (total_completion_tokens / 1000) * 0.002
+                total_cost = input_cost + output_cost
+
+                # Add usage summary to logs
+                usage_summary = f"\n\n💰 CREDITS USED:\n"
+                usage_summary += f"  Input:  {total_prompt_tokens:,} tokens (${input_cost:.4f})\n"
+                usage_summary += f"  Output: {total_completion_tokens:,} tokens (${output_cost:.4f})\n"
+                usage_summary += f"  Total:  {total_tokens:,} tokens (${total_cost:.4f})"
+
+                # Update message with filtered logs + usage
+                log_msg.content = f"```\n{filtered_output}\n{usage_summary}\n```"
+                await log_msg.update()
+
+        # Get final result
+        result = await future
+
+        # Get final logs
+        final_logs = captured_output.getvalue()
+
+        # Update with final logs
+        log_msg.content = f"## 📋 Execution Log\n```\n{final_logs}\n```"
+        await log_msg.update()
+
+        # Send results summary
+        summary_lines = []
+
+        if result.get('plan'):
+            summary_lines.append("## 🤔 Planner")
+            summary_lines.append(f"✅ Plan created ({len(result['plan'])} chars)\n")
+
+        if result.get('code_changes'):
+            summary_lines.append("## 💻 Coder")
+            summary_lines.append(f"✅ Created {len(result['code_changes'])} file(s):")
+            for file_path in result['code_changes'].keys():
+                summary_lines.append(f"  - {file_path}")
+            summary_lines.append("")
+
+        if result.get('review_feedback'):
+            summary_lines.append("## 👁️ Reviewer")
+            if result.get('success'):
+                summary_lines.append("✅ Code approved")
+            else:
+                summary_lines.append("⚠️ Needs revision")
+            summary_lines.append("")
+
+        summary_lines.append("## 🎯 Result")
+        if result.get('success'):
+            summary_lines.append(f"✅ **Success** (Iterations: {result.get('iterations', 'N/A')})")
+        else:
+            summary_lines.append(f"⚠️ **Incomplete** (Iterations: {result.get('iterations', 'N/A')})")
+
+        # Add final cost summary
+        summary_lines.append("\n## 💰 API Credits Used (GPT-3.5-Turbo)")
+        summary_lines.append(f"**Total Tokens:** {total_tokens:,}")
+        summary_lines.append(f"- Input: {total_prompt_tokens:,} tokens (${(total_prompt_tokens/1000)*0.0015:.4f})")
+        summary_lines.append(f"- Output: {total_completion_tokens:,} tokens (${(total_completion_tokens/1000)*0.002:.4f})")
+        summary_lines.append(f"\n**Estimated Cost:** ${total_cost:.4f}")
+
+        await cl.Message(content="\n".join(summary_lines)).send()
+
+    except Exception as e:
+        # Determine error type and provide specific guidance
+        error_message = str(e)
+        error_type = type(e).__name__
+
+        if "rate_limit" in error_message.lower() or "429" in error_message:
+            user_message = f"""## ⏱️ Rate Limit Reached
+
+OpenAI API rate limit exceeded. This happens when too many requests are made in a short time.
+
+**What to do:**
+- Wait a few minutes and try again
+- Reduce max_iterations (currently: {orchestrator.max_iterations})
+- Your request will work once the rate limit resets
+
+**Error details:**
+```
+{error_message}
+```
+"""
+        elif "insufficient_quota" in error_message.lower():
+            user_message = f"""## 💳 API Credits Exhausted
+
+Your OpenAI API credits have been exhausted.
+
+**What to do:**
+- Add credits to your OpenAI account at https://platform.openai.com/account/billing
+- Check your usage at https://platform.openai.com/usage
+- Current model: GPT-3.5-turbo (~$0.02 per task)
+
+**Error details:**
+```
+{error_message}
+```
+"""
+        elif "api_key" in error_message.lower() or "authentication" in error_message.lower():
+            user_message = f"""## 🔑 API Key Error
+
+There's an issue with your OpenAI API key.
+
+**What to do:**
+- Verify your OPENAI_API_KEY in .env file
+- Check that the key is valid at https://platform.openai.com/api-keys
+- Restart the application after updating .env
+
+**Error details:**
+```
+{error_message}
+```
+"""
+        elif "timeout" in error_message.lower():
+            user_message = f"""## ⏰ Request Timeout
+
+The operation took too long and timed out.
+
+**What to do:**
+- Try again with a simpler task
+- The task may be too complex for one iteration
+- Consider breaking it into smaller steps
+
+**Error details:**
+```
+{error_message}
+```
+"""
+        else:
+            # Generic error with helpful context
+            user_message = f"""## ❌ Error Occurred
+
+An unexpected error occurred during execution.
+
+**Error type:** {error_type}
+
+**What to do:**
+- Try rephrasing your request
+- Check if all required files/dependencies exist
+- Verify your .env file has all required API keys
+
+**Error details:**
+```
+{error_message}
+```
+
+If this persists, please report the issue with the error details above.
+"""
+
+        await cl.Message(content=user_message).send()
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit("Run with: chainlit run chainlit_app.py")

codepilot/agents/base_agent.py

@@ -0,0 +1,161 @@
+"""
+Base Agent
+The main agent loop that orchestrates LLM calls and tool execution
+"""
+
+import json
+from codepilot.llm.client import OpenAIClient
+from codepilot.agents.conversation import ConversationManager
+from codepilot.tools.registry import get_tools, get_tool_function
+
+
+class Agent:
+    """Main agent that executes tasks using LLM and tools"""
+
+    def __init__(self, model: str = "gpt-3.5-turbo", max_iterations: int = 10):
+        """
+        Initialize the agent
+
+        Args:
+            model: OpenAI model to use
+            max_iterations: Maximum number of LLM calls to prevent infinite loops
+        """
+        print("🚀 Initializing Agent...")
+
+        # Initialize components
+        self.client = OpenAIClient(model=model)
+        self.conversation = ConversationManager()
+        self.tools = get_tools()
+        self.max_iterations = max_iterations
+
+        print(f"✅ Agent ready with {len(self.tools)} tools")
+        print(f"   Max iterations: {max_iterations}\n")
+
+    def run(self, user_prompt: str) -> str:
+        """
+        Run the agent with a user prompt
+
+        Args:
+            user_prompt: The user's request
+
+        Returns:
+            Final response from the agent
+        """
+        print("=" * 60)
+        print("🤖 AGENT STARTING")
+        print("=" * 60)
+
+        # Add user message to conversation
+        self.conversation.add_user_message(user_prompt)
+
+        # Main agent loop
+        for iteration in range(1, self.max_iterations + 1):
+            print(f"\n--- Iteration {iteration}/{self.max_iterations} ---")
+
+            # Call OpenAI with current conversation and tools
+            response = self.client.chat(
+                messages=self.conversation.get_messages(),
+                tools=self.tools
+            )
+
+            # Get the assistant's response
+            message = response.choices[0].message
+            finish_reason = response.choices[0].finish_reason
+
+            print(f"🎯 Finish reason: {finish_reason}")
+
+            # Check what the assistant wants to do
+            if finish_reason == "stop":
+                # Assistant is done, has a text response
+                final_response = message.content
+                self.conversation.add_assistant_message(final_response)
+
+                print("\n" + "=" * 60)
+                print("✅ AGENT COMPLETE")
+                print("=" * 60)
+
+                return final_response
+
+            elif finish_reason == "tool_calls":
+                # Assistant wants to use tools
+                tool_calls = message.tool_calls
+
+                # Add the assistant's tool calls to conversation
+                self.conversation.add_assistant_tool_calls(tool_calls)
+
+                # Execute each tool call
+                for tool_call in tool_calls:
+                    self._execute_tool_call(tool_call)
+
+                # Continue loop - send results back to OpenAI
+                continue
+
+            else:
+                # Unexpected finish reason
+                error_msg = f"Unexpected finish_reason: {finish_reason}"
+                print(f"⚠️  {error_msg}")
+                return error_msg
+
+        # Max iterations reached
+        max_iter_msg = f"⚠️  Reached maximum iterations ({self.max_iterations})"
+        print(f"\n{max_iter_msg}")
+        return max_iter_msg
+
+    def _execute_tool_call(self, tool_call):
+        """
+        Execute a single tool call
+
+        Args:
+            tool_call: Tool call object from OpenAI response
+        """
+        tool_id = tool_call.id
+        tool_name = tool_call.function.name
+        tool_args_json = tool_call.function.arguments
+
+        print(f"\n🔧 Executing tool: {tool_name}")
+        print(f"   ID: {tool_id}")
+        print(f"   Arguments: {tool_args_json}")
+
+        try:
+            # Parse arguments from JSON string
+            tool_args = json.loads(tool_args_json)
+
+            # Get the tool function
+            tool_function = get_tool_function(tool_name)
+
+            if tool_function is None:
+                result = f"Error: Tool '{tool_name}' not found in registry"
+                print(f"❌ {result}")
+            else:
+                # Execute the tool
+                result = tool_function(**tool_args)
+
+            # Add result to conversation
+            self.conversation.add_tool_result(
+                tool_call_id=tool_id,
+                tool_name=tool_name,
+                result=result
+            )
+
+        except json.JSONDecodeError as e:
+            error_msg = f"Error parsing tool arguments: {e}"
+            print(f"❌ {error_msg}")
+            self.conversation.add_tool_result(
+                tool_call_id=tool_id,
+                tool_name=tool_name,
+                result=error_msg
+            )
+
+        except Exception as e:
+            error_msg = f"Error executing tool: {str(e)}"
+            print(f"❌ {error_msg}")
+            self.conversation.add_tool_result(
+                tool_call_id=tool_id,
+                tool_name=tool_name,
+                result=error_msg
+            )
+
+    def reset(self):
+        """Reset the agent's conversation history"""
+        self.conversation.clear()
+        print("🔄 Agent conversation reset")

codepilot/agents/coder_agent.py

@@ -0,0 +1,202 @@
+"""
+Coder Agent - Implements code based on plans
+
+The Coder's job:
+1. Read the plan from Planner
+2. Search/read existing code to understand it
+3. Write code changes to implement the plan
+4. Follow best practices and coding standards
+
+Tools it has access to:
+- search_codebase (find relevant files)
+- read_file (understand existing code)
+- write_file (implement changes)
+- list_files (explore structure)
+"""
+
+from codepilot.llm.client import OpenAIClient
+from codepilot.tools.registry import get_tools, get_tool_function
+from codepilot.agents.conversation import ConversationManager
+from typing import Dict, Any
+import json
+
+
+# Coder's specialized system prompt
+CODER_SYSTEM_PROMPT = """You are an expert software engineer and implementation specialist.
+
+Your ONLY job is to write code that implements the given plan. You do NOT create plans yourself.
+
+When given a plan:
+1. Read and understand each step carefully
+2. Search the codebase to find relevant files
+3. Read existing files to understand the current implementation
+4. Write clean, well-structured code that follows the plan
+5. Make incremental changes, one step at a time
+
+Your code should be:
+- Clean and readable (follow existing code style)
+- Well-tested (add error handling)
+- Documented (add comments for complex logic)
+- Minimal (only change what's necessary)
+
+IMPORTANT RULES:
+- Follow the plan exactly - don't add extra features
+- Match the existing code style in each file
+- Test your changes mentally before writing
+- If you need clarification on the plan, state what's unclear
+
+Tools available to you:
+- search_codebase: Find existing code
+- read_file: Understand current implementation
+- write_file: Create or modify files
+- list_files: Explore directory structure
+- upload_to_sandbox: Upload files to isolated testing environment
+- run_command_in_sandbox: Run commands safely in sandbox (e.g., pytest, python test.py)
+- execute_in_sandbox: Execute Python code snippets for quick testing
+
+IMPORTANT: Always test your code in the sandbox before submitting!
+1. Write the file locally (write_file)
+2. Upload to sandbox (upload_to_sandbox)
+3. Run tests in sandbox (run_command_in_sandbox)
+4. Fix any issues before marking as complete
+"""
+
+
+class CoderAgent:
+    """
+    Coder Agent - Implements code based on plans.
+
+    This agent is specialized for coding. It has:
+    - Custom system prompt (engineer mindset)
+    - Write access tools (can modify files)
+    - Single responsibility (implementation only)
+    """
+
+    def __init__(self, model: str = "gpt-3.5-turbo"):
+        """
+        Initialize Coder agent.
+
+        Args:
+            model: LLM model to use
+        """
+        self.client = OpenAIClient(model=model)
+        self.conversation = ConversationManager()
+
+        # Coder gets read + write tools + sandbox execution (safe testing)
+        self.allowed_tools = [
+            "search_codebase",
+            "read_file",
+            "write_file",
+            "list_files",
+            "upload_to_sandbox",
+            "run_command_in_sandbox",
+            "execute_in_sandbox"
+        ]
+
+    def run(self, plan: str, task: str, review_feedback: str = None) -> Dict[str, str]:
+        """
+        Implement the given plan.
+
+        Args:
+            plan: Implementation plan from Planner
+            task: Original task description (for context)
+            review_feedback: Optional feedback from Reviewer if code was rejected
+
+        Returns:
+            Dictionary mapping file paths to their new content
+        """
+        # Reset conversation
+        self.conversation = ConversationManager()
+
+        # Add system prompt
+        self.conversation.add_message("system", CODER_SYSTEM_PROMPT)
+
+        # Build user prompt with task, plan, and optionally review feedback
+        user_prompt = f"""Original Task: {task}
+
+Implementation Plan:
+{plan}"""
+
+        # If this is a rework (Reviewer rejected the code), include feedback
+        if review_feedback:
+            user_prompt += f"""
+
+IMPORTANT - REVIEWER FEEDBACK (CODE WAS REJECTED):
+{review_feedback}
+
+Please fix the issues mentioned by the Reviewer and resubmit the code."""
+        else:
+            user_prompt += """
+
+Please implement this plan step by step. Write clean, well-structured code that follows the plan."""
+
+        self.conversation.add_message("user", user_prompt)
+
+        # Get only the tools this agent is allowed to use
+        all_tools = get_tools()
+        coder_tools = [
+            tool for tool in all_tools
+            if tool['function']['name'] in self.allowed_tools
+        ]
+
+        # Track which files were modified
+        modified_files = {}
+
+        # Run coding loop (agent reads code, writes changes)
+        max_iterations = 15  # Coder might need more iterations than planner
+        for iteration in range(max_iterations):
+            # Call LLM
+            response = self.client.chat(
+                messages=self.conversation.get_messages(),
+                tools=coder_tools
+            )
+
+            finish_reason = response.choices[0].finish_reason
+            message = response.choices[0].message
+
+            # Add assistant response to conversation
+            self.conversation.add_message(
+                role="assistant",
+                content=message.content,
+                tool_calls=message.tool_calls
+            )
+
+            # Check if done
+            if finish_reason == "stop":
+                # Agent finished coding
+                print(f"[CODER] Finished implementation")
+                return modified_files
+
+            # Execute tool calls
+            if finish_reason == "tool_calls":
+                for tool_call in message.tool_calls:
+                    tool_name = tool_call.function.name
+                    tool_args = json.loads(tool_call.function.arguments)
+
+                    print(f"[CODER] Calling tool: {tool_name}({tool_args})")
+
+                    # Execute tool
+                    tool_func = get_tool_function(tool_name)
+                    if tool_func:
+                        result = tool_func(**tool_args)
+
+                        # Track file modifications
+                        if tool_name == "write_file" and "path" in tool_args:
+                            modified_files[tool_args["path"]] = tool_args.get("content", "")
+                    else:
+                        result = f"Error: Tool {tool_name} not found"
+
+                    # Add tool result to conversation
+                    self.conversation.add_tool_result(
+                        tool_call_id=tool_call.id,
+                        tool_name=tool_name,
+                        result=str(result)
+                    )
+
+        # If we hit max iterations, return what we have
+        print(f"[CODER] Warning: Hit max iterations ({max_iterations})")
+        return modified_files
+
+    def get_tool_access(self) -> list:
+        """Return list of tools this agent can access."""
+        return self.allowed_tools

codepilot/agents/conversation.py

@@ -0,0 +1,137 @@
+"""
+Conversation Manager
+Handles conversation history in OpenAI's message format
+"""
+
+from typing import List, Dict, Any
+
+
+class ConversationManager:
+    """Manages conversation history for the agent"""
+
+    def __init__(self):
+        """Initialize with empty message history"""
+        self.messages: List[Dict[str, Any]] = []
+
+    def add_message(self, role: str, content: str, tool_calls=None):
+        """
+        Generic method to add any message to conversation.
+
+        Args:
+            role: Message role ("system", "user", "assistant", "tool")
+            content: Message content
+            tool_calls: Optional tool calls for assistant messages
+        """
+        message = {"role": role, "content": content}
+        if tool_calls:
+            message["tool_calls"] = tool_calls
+        self.messages.append(message)
+
+    def add_user_message(self, content: str):
+        """
+        Add a user message to the conversation
+
+        Args:
+            content: The user's message text
+        """
+        self.messages.append({
+            "role": "user",
+            "content": content
+        })
+        print(f"👤 User: {content[:100]}..." if len(content) > 100 else f"👤 User: {content}")
+
+    def add_assistant_message(self, content: str):
+        """
+        Add an assistant text response to the conversation
+
+        Args:
+            content: The assistant's response text
+        """
+        self.messages.append({
+            "role": "assistant",
+            "content": content
+        })
+        print(f"🤖 Assistant: {content[:100]}..." if len(content) > 100 else f"🤖 Assistant: {content}")
+
+    def add_assistant_tool_calls(self, tool_calls: List[Any]):
+        """
+        Add an assistant message with tool calls
+
+        Args:
+            tool_calls: List of tool call objects from OpenAI response
+        """
+        # Extract tool call info for logging
+        tool_names = [tc.function.name for tc in tool_calls]
+        print(f"🔧 Assistant calling tools: {tool_names}")
+
+        # OpenAI requires this specific format
+        self.messages.append({
+            "role": "assistant",
+            "content": None,  # No text content when making tool calls
+            "tool_calls": [
+                {
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {
+                        "name": tc.function.name,
+                        "arguments": tc.function.arguments
+                    }
+                }
+                for tc in tool_calls
+            ]
+        })
+
+    def add_tool_result(self, tool_call_id: str, tool_name: str, result: str):
+        """
+        Add a tool execution result to the conversation
+
+        Args:
+            tool_call_id: The ID of the tool call (from OpenAI)
+            tool_name: Name of the tool that was executed
+            result: The result string from the tool
+        """
+        self.messages.append({
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "name": tool_name,
+            "content": result
+        })
+        # Truncate long results for logging
+        result_preview = result[:100] + "..." if len(result) > 100 else result
+        print(f"✅ Tool {tool_name} result: {result_preview}")
+
+    def get_messages(self) -> List[Dict[str, Any]]:
+        """
+        Get the full conversation history
+
+        Returns:
+            List of message dictionaries
+        """
+        return self.messages
+
+    def clear(self):
+        """Clear all messages from history"""
+        self.messages = []
+        print("🗑️  Conversation cleared")
+
+    def get_message_count(self) -> int:
+        """
+        Get the number of messages in the conversation
+
+        Returns:
+            Number of messages
+        """
+        return len(self.messages)
+
+    def print_summary(self):
+        """Print a summary of the conversation"""
+        print(f"\n📊 Conversation Summary:")
+        print(f"  Total messages: {len(self.messages)}")
+
+        role_counts = {}
+        for msg in self.messages:
+            role = msg.get("role", "unknown")
+            role_counts[role] = role_counts.get(role, 0) + 1
+
+        for role, count in role_counts.items():
+            print(f"  {role}: {count}")

codepilot/agents/orchestrator.py

@@ -0,0 +1,227 @@
+"""
+Orchestrator - Manages multi-agent workflow
+
+The orchestrator is the "brain" that:
+1. Tracks current state (planning, coding, reviewing, etc.)
+2. Decides which agent to call next
+3. Manages communication between agents
+4. Handles the overall task flow
+"""
+
+from enum import Enum
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+from codepilot.agents.planner_agent import PlannerAgent
+from codepilot.agents.coder_agent import CoderAgent
+from codepilot.agents.reviewer_agent import ReviewerAgent
+
+
+class AgentState(Enum):
+    """Possible states in the multi-agent workflow"""
+    PLANNING = "planning"
+    CODING = "coding"
+    REVIEWING = "reviewing"
+    COMPLETE = "complete"
+    FAILED = "failed"
+
+
+@dataclass
+class TaskContext:
+    """
+    Shared context passed between agents.
+
+    Think of this as a clipboard that agents write to and read from.
+    """
+    task_description: str  # Original task from user
+    plan: Optional[str] = None  # Created by Planner
+    code_changes: Optional[Dict[str, str]] = None  # Created by Coder
+    review_feedback: Optional[str] = None  # Created by Reviewer
+    error_message: Optional[str] = None  # Set if something fails
+
+    # Metadata
+    current_step: int = 0
+    total_steps: int = 0
+    iterations: int = 0  # How many times we've looped
+
+
+class Orchestrator:
+    """
+    Orchestrator manages the multi-agent workflow.
+
+    Flow:
+    1. Start in PLANNING state
+    2. Call Planner agent → get plan
+    3. Transition to CODING state
+    4. Call Coder agent → get code
+    5. Transition to REVIEWING state
+    6. Call Reviewer agent → get feedback
+    7. If approved → COMPLETE
+       If rejected → back to CODING (loop)
+    """
+
+    def __init__(self, max_iterations: int = 5):
+        """
+        Initialize orchestrator.
+
+        Args:
+            max_iterations: Max loops between coding and reviewing
+                           (prevents infinite loops if code keeps failing)
+        """
+        self.state = AgentState.PLANNING
+        self.max_iterations = max_iterations
+        self.context = None
+
+        # Create agent instances
+        self.planner = PlannerAgent()
+        self.coder = CoderAgent()
+        self.reviewer = ReviewerAgent()
+
+    def run(self, task: str) -> Dict[str, Any]:
+        """
+        Run the multi-agent workflow for a task.
+
+        Args:
+            task: User's task description (e.g., "Add a login feature")
+
+        Returns:
+            Result dict with status, changes, and messages
+        """
+        # Initialize context
+        self.context = TaskContext(task_description=task)
+        self.state = AgentState.PLANNING
+
+        # Main state machine loop
+        while self.state not in [AgentState.COMPLETE, AgentState.FAILED]:
+            # Safety: prevent infinite loops
+            if self.context.iterations >= self.max_iterations:
+                self.state = AgentState.FAILED
+                self.context.error_message = f"Max iterations ({self.max_iterations}) exceeded"
+                break
+
+            # Execute current state
+            if self.state == AgentState.PLANNING:
+                self._execute_planning()
+
+            elif self.state == AgentState.CODING:
+                self._execute_coding()
+
+            elif self.state == AgentState.REVIEWING:
+                self._execute_reviewing()
+
+            self.context.iterations += 1
+
+        # Return final result
+        return self._build_result()
+
+    def _execute_planning(self):
+        """
+        Execute planning state: call Planner agent.
+
+        Planner's job:
+        - Understand the task
+        - Search codebase for relevant files
+        - Create step-by-step plan
+
+        Transition: Always go to CODING next
+        """
+        print(f"\n[ORCHESTRATOR] State: PLANNING")
+        print(f"[ORCHESTRATOR] Task: {self.context.task_description}")
+
+        # Call the real Planner agent!
+        self.context.plan = self.planner.run(self.context.task_description)
+
+        # Transition to coding
+        self.state = AgentState.CODING
+        print(f"[ORCHESTRATOR] Plan created. Transitioning to CODING")
+
+    def _execute_coding(self):
+        """
+        Execute coding state: call Coder agent.
+
+        Coder's job:
+        - Read the plan
+        - Read relevant files
+        - Write code changes
+
+        Transition: Always go to REVIEWING next
+        """
+        print(f"\n[ORCHESTRATOR] State: CODING")
+
+        # Check if this is a rework (Reviewer rejected previous code)
+        if self.context.review_feedback:
+            print(f"[ORCHESTRATOR] Passing plan + REVIEWER FEEDBACK to Coder agent...")
+        else:
+            print(f"[ORCHESTRATOR] Passing plan to Coder agent...")
+
+        # Call the real Coder agent (with review feedback if available)!
+        self.context.code_changes = self.coder.run(
+            plan=self.context.plan,
+            task=self.context.task_description,
+            review_feedback=self.context.review_feedback
+        )
+
+        # Transition to reviewing
+        self.state = AgentState.REVIEWING
+        print(f"[ORCHESTRATOR] Code written. Transitioning to REVIEWING")
+
+    def _execute_reviewing(self):
+        """
+        Execute reviewing state: call Reviewer agent.
+
+        Reviewer's job:
+        - Read the code changes
+        - Check for bugs, style issues
+        - Approve or reject
+
+        Transition:
+        - If approved → COMPLETE
+        - If rejected → back to CODING (with feedback)
+        """
+        print(f"\n[ORCHESTRATOR] State: REVIEWING")
+        print(f"[ORCHESTRATOR] Passing code changes to Reviewer agent...")
+
+        # Call the real Reviewer agent!
+        approved, feedback = self.reviewer.run(
+            code_changes=self.context.code_changes,
+            plan=self.context.plan,
+            task=self.context.task_description
+        )
+
+        # Store the feedback
+        self.context.review_feedback = feedback
+
+        if approved:
+            print(f"[ORCHESTRATOR] Code APPROVED. Transitioning to COMPLETE")
+            self.state = AgentState.COMPLETE
+        else:
+            print(f"[ORCHESTRATOR] Code REJECTED. Transitioning back to CODING")
+            self.state = AgentState.CODING
+
+    def _build_result(self) -> Dict[str, Any]:
+        """
+        Build final result dictionary.
+
+        Returns:
+            Dict with status, code changes, and metadata
+        """
+        return {
+            'status': self.state.value,
+            'success': self.state == AgentState.COMPLETE,
+            'task': self.context.task_description,
+            'plan': self.context.plan,
+            'code_changes': self.context.code_changes,
+            'review_feedback': self.context.review_feedback,
+            'error': self.context.error_message,
+            'iterations': self.context.iterations
+        }
+
+    def get_state_history(self) -> str:
+        """Get a summary of the orchestration flow."""
+        return f"""
+Orchestrator Summary:
+- Final State: {self.state.value}
+- Iterations: {self.context.iterations}
+- Task: {self.context.task_description}
+- Plan Created: {'Yes' if self.context.plan else 'No'}
+- Code Written: {'Yes' if self.context.code_changes else 'No'}
+"""

codepilot/agents/planner_agent.py

@@ -0,0 +1,157 @@
+"""
+Planner Agent - Creates implementation plans
+
+The Planner's job:
+1. Understand the task
+2. Search the codebase to see what exists
+3. Create a detailed, step-by-step plan
+
+Tools it has access to:
+- search_codebase (hybrid retrieval)
+- read_file (to understand existing code)
+- list_files (to explore structure)
+"""
+
+from codepilot.llm.client import OpenAIClient
+from codepilot.tools.registry import get_tools, get_tool_function
+from codepilot.agents.conversation import ConversationManager
+from typing import Dict, Any
+import json
+
+
+# Planner's specialized system prompt
+PLANNER_SYSTEM_PROMPT = """You are a senior software architect and planning expert.
+
+Your ONLY job is to create detailed implementation plans. You do NOT write code.
+
+When given a task:
+1. First, search the codebase to understand what already exists
+2. Identify which files need to be modified or created
+3. Break down the task into clear, specific steps
+4. Consider dependencies and potential risks
+
+Your plan should be:
+- Specific (mention exact file names, function names)
+- Ordered (steps build on each other)
+- Complete (covers all aspects of the task)
+- Realistic (considers existing code structure)
+
+Output your plan as a numbered list of steps.
+
+Tools available to you:
+- search_codebase: Search for existing code (use this first!)
+- read_file: Read specific files to understand them
+- list_files: Explore directory structure
+
+You do NOT have write_file or run_command - you only plan, never execute.
+"""
+
+
+class PlannerAgent:
+    """
+    Planner Agent - Creates implementation plans.
+
+    This agent is specialized for planning. It has:
+    - Custom system prompt (architect mindset)
+    - Limited tools (read-only)
+    - Single responsibility (planning only)
+    """
+
+    def __init__(self, model: str = "gpt-3.5-turbo"):
+        """
+        Initialize Planner agent.
+
+        Args:
+            model: LLM model to use
+        """
+        self.client = OpenAIClient(model=model)
+        self.conversation = ConversationManager()
+
+        # Planner only gets read-only tools
+        self.allowed_tools = [
+            "search_codebase",
+            "read_file",
+            "list_files"
+        ]
+
+    def run(self, task: str) -> str:
+        """
+        Create a plan for the given task.
+
+        Args:
+            task: Task description (e.g., "Add login feature")
+
+        Returns:
+            Detailed implementation plan as a string
+        """
+        # Reset conversation
+        self.conversation = ConversationManager()
+
+        # Add system prompt
+        self.conversation.add_message("system", PLANNER_SYSTEM_PROMPT)
+
+        # Add user task
+        user_prompt = f"""Task: {task}
+
+Please create a detailed implementation plan. Start by searching the codebase to understand what exists."""
+        self.conversation.add_message("user", user_prompt)
+
+        # Get only the tools this agent is allowed to use
+        all_tools = get_tools()
+        planner_tools = [
+            tool for tool in all_tools
+            if tool['function']['name'] in self.allowed_tools
+        ]
+
+        # Run planning loop (agent explores codebase, then creates plan)
+        max_iterations = 10
+        for iteration in range(max_iterations):
+            # Call LLM
+            response = self.client.chat(
+                messages=self.conversation.get_messages(),
+                tools=planner_tools
+            )
+
+            finish_reason = response.choices[0].finish_reason
+            message = response.choices[0].message
+
+            # Add assistant response to conversation
+            self.conversation.add_message(
+                role="assistant",
+                content=message.content,
+                tool_calls=message.tool_calls
+            )
+
+            # Check if done
+            if finish_reason == "stop":
+                # Agent finished planning
+                return message.content
+
+            # Execute tool calls
+            if finish_reason == "tool_calls":
+                for tool_call in message.tool_calls:
+                    tool_name = tool_call.function.name
+                    tool_args = json.loads(tool_call.function.arguments)
+
+                    print(f"[PLANNER] Calling tool: {tool_name}({tool_args})")
+
+                    # Execute tool
+                    tool_func = get_tool_function(tool_name)
+                    if tool_func:
+                        result = tool_func(**tool_args)
+                    else:
+                        result = f"Error: Tool {tool_name} not found"
+
+                    # Add tool result to conversation
+                    self.conversation.add_tool_result(
+                        tool_call_id=tool_call.id,
+                        tool_name=tool_name,
+                        result=str(result)
+                    )
+
+        # If we hit max iterations, return what we have
+        return "Error: Planner exceeded max iterations"
+
+    def get_tool_access(self) -> list:
+        """Return list of tools this agent can access."""
+        return self.allowed_tools

codepilot/agents/reviewer_agent.py

@@ -0,0 +1,238 @@
+"""
+Reviewer Agent - Reviews code for quality and correctness
+
+The Reviewer's job:
+1. Read the code changes from Coder
+2. Check for bugs, security issues, style problems
+3. Verify the code matches the plan
+4. Either approve or reject with specific feedback
+
+Tools it has access to:
+- read_file (to see full context of changed files)
+- search_codebase (to check for similar patterns)
+"""
+
+from codepilot.llm.client import OpenAIClient
+from codepilot.tools.registry import get_tools, get_tool_function
+from codepilot.agents.conversation import ConversationManager
+from typing import Dict, Any, Tuple
+import json
+
+
+# Reviewer's specialized system prompt
+REVIEWER_SYSTEM_PROMPT = """You are a senior code reviewer and quality assurance expert.
+
+Your ONLY job is to review code changes and provide feedback. You do NOT write code yourself.
+
+When given code changes:
+1. Read each changed file carefully
+2. Check for common issues:
+   - Bugs and logic errors
+   - Security vulnerabilities (SQL injection, XSS, etc.)
+   - Missing error handling
+   - Poor naming or unclear code
+   - Code that doesn't match the plan
+3. Decide: APPROVE or REJECT
+4. If rejecting, provide specific, actionable feedback
+
+Your review should be:
+- Thorough (check all aspects of the code)
+- Specific (point to exact issues with line numbers if possible)
+- Constructive (explain WHY something is wrong and HOW to fix it)
+- Fair (don't reject for minor style issues)
+
+DECISION CRITERIA:
+✅ APPROVE if:
+- Code works correctly
+- No security issues
+- Follows the plan
+- Has basic error handling
+- Is reasonably readable
+
+❌ REJECT if:
+- Code has bugs
+- Security vulnerabilities exist
+- Doesn't implement the plan
+- Missing critical error handling
+- Code is unclear or confusing
+
+Tools available to you:
+- read_file: Read files to understand full context
+- search_codebase: Check for similar patterns in the codebase
+
+You do NOT have write_file - you only review, never modify code.
+"""
+
+
+class ReviewerAgent:
+    """
+    Reviewer Agent - Reviews code for quality and correctness.
+
+    This agent is specialized for code review. It has:
+    - Custom system prompt (quality assurance mindset)
+    - Read-only tools (cannot modify code)
+    - Single responsibility (review only)
+    """
+
+    def __init__(self, model: str = "gpt-3.5-turbo"):
+        """
+        Initialize Reviewer agent.
+
+        Args:
+            model: LLM model to use
+        """
+        self.client = OpenAIClient(model=model)
+        self.conversation = ConversationManager()
+
+        # Reviewer only gets read-only tools
+        self.allowed_tools = [
+            "read_file",
+            "search_codebase"
+        ]
+
+    def run(self, code_changes: Dict[str, str], plan: str, task: str) -> Tuple[bool, str]:
+        """
+        Review the code changes.
+
+        Args:
+            code_changes: Dictionary mapping file paths to new content
+            plan: The original plan (to verify code matches)
+            task: The original task (for context)
+
+        Returns:
+            Tuple of (approved: bool, feedback: str)
+            - approved: True if code is good, False if needs changes
+            - feedback: Explanation of decision and any issues found
+        """
+        # Reset conversation
+        self.conversation = ConversationManager()
+
+        # Add system prompt
+        self.conversation.add_message("system", REVIEWER_SYSTEM_PROMPT)
+
+        # Format code changes for review
+        changes_text = self._format_code_changes(code_changes)
+
+        # Add user prompt with task, plan, and code changes
+        user_prompt = f"""Original Task: {task}
+
+Implementation Plan:
+{plan}
+
+Code Changes to Review:
+{changes_text}
+
+Please review these code changes carefully. Check for bugs, security issues, and whether the code correctly implements the plan.
+
+End your review with a clear decision:
+- "DECISION: APPROVE" if the code is good
+- "DECISION: REJECT" if changes are needed
+
+If rejecting, provide specific feedback on what needs to be fixed."""
+        self.conversation.add_message("user", user_prompt)
+
+        # Get only the tools this agent is allowed to use
+        all_tools = get_tools()
+        reviewer_tools = [
+            tool for tool in all_tools
+            if tool['function']['name'] in self.allowed_tools
+        ]
+
+        # Run review loop
+        max_iterations = 10
+        for iteration in range(max_iterations):
+            # Call LLM
+            response = self.client.chat(
+                messages=self.conversation.get_messages(),
+                tools=reviewer_tools
+            )
+
+            finish_reason = response.choices[0].finish_reason
+            message = response.choices[0].message
+
+            # Add assistant response to conversation
+            self.conversation.add_message(
+                role="assistant",
+                content=message.content,
+                tool_calls=message.tool_calls
+            )
+
+            # Check if done
+            if finish_reason == "stop":
+                # Agent finished review, parse decision
+                return self._parse_review_decision(message.content)
+
+            # Execute tool calls
+            if finish_reason == "tool_calls":
+                for tool_call in message.tool_calls:
+                    tool_name = tool_call.function.name
+                    tool_args = json.loads(tool_call.function.arguments)
+
+                    print(f"[REVIEWER] Calling tool: {tool_name}({tool_args})")
+
+                    # Execute tool
+                    tool_func = get_tool_function(tool_name)
+                    if tool_func:
+                        result = tool_func(**tool_args)
+                    else:
+                        result = f"Error: Tool {tool_name} not found"
+
+                    # Add tool result to conversation
+                    self.conversation.add_tool_result(
+                        tool_call_id=tool_call.id,
+                        tool_name=tool_name,
+                        result=str(result)
+                    )
+
+        # If we hit max iterations, default to reject
+        return False, "Review timed out - please try again"
+
+    def _format_code_changes(self, code_changes: Dict[str, str]) -> str:
+        """
+        Format code changes into readable text.
+
+        Args:
+            code_changes: Dict mapping file paths to content
+
+        Returns:
+            Formatted string showing all changes
+        """
+        if not code_changes:
+            return "No code changes to review."
+
+        formatted = []
+        for file_path, content in code_changes.items():
+            formatted.append(f"\n{'='*60}")
+            formatted.append(f"File: {file_path}")
+            formatted.append('='*60)
+            formatted.append(content)
+
+        return '\n'.join(formatted)
+
+    def _parse_review_decision(self, review_text: str) -> Tuple[bool, str]:
+        """
+        Parse the review text to extract decision.
+
+        Args:
+            review_text: The reviewer's final response
+
+        Returns:
+            Tuple of (approved, feedback)
+        """
+        if review_text is None:
+            return False, "No review provided"
+
+        # Look for decision in the text
+        review_lower = review_text.lower()
+
+        if "decision: approve" in review_lower:
+            return True, review_text
+        elif "decision: reject" in review_lower:
+            return False, review_text
+        else:
+            # No clear decision - default to reject for safety
+            return False, f"Unclear decision. Review:\n{review_text}"
+
+    def get_tool_access(self) -> list:
+        """Return list of tools this agent can access."""
+        return self.allowed_tools

codepilot/context/__init__.py

@@ -0,0 +1,8 @@
+"""
+Context Engineering Module
+Provides code parsing, indexing, and intelligent context selection
+"""
+
+from codepilot.context.parser import CodeParser
+
+__all__ = ['CodeParser']

codepilot/context/bm25_retriever.py

@@ -0,0 +1,175 @@
+"""
+BM25 Retriever - Keyword-based code search
+
+BM25 (Best Matching 25) is a ranking function that scores documents by:
+1. Term Frequency (TF) - How often the search term appears in a document
+2. Inverse Document Frequency (IDF) - Rarer terms get higher scores
+3. Document Length Normalization - Longer docs don't unfairly dominate
+
+This is the "keyword" half of our hybrid retrieval system.
+"""
+
+import re
+from typing import List, Dict, Any, Tuple
+from rank_bm25 import BM25Okapi
+
+
+class CodeTokenizer:
+    """
+    Tokenize code for searchability.
+
+    Handles:
+    - camelCase: getUserById -> get, user, by, id
+    - snake_case: get_user_by_id -> get, user, by, id
+    - Removes common Python keywords (they appear everywhere, low signal)
+    """
+
+    # Python keywords that appear in almost every file (low IDF = useless for search)
+    STOP_WORDS = {
+        'def', 'class', 'return', 'self', 'if', 'else', 'elif', 'for', 'while',
+        'try', 'except', 'finally', 'with', 'as', 'import', 'from', 'in', 'is',
+        'not', 'and', 'or', 'none', 'true', 'false', 'pass', 'break', 'continue',
+        'lambda', 'yield', 'raise', 'assert', 'global', 'nonlocal', 'del',
+        'the', 'a', 'an', 'of', 'to', 'args', 'kwargs', 'init', 'str', 'int',
+        'list', 'dict', 'bool', 'float', 'type', 'any', 'optional'
+    }
+
+    def tokenize(self, text: str) -> List[str]:
+        """
+        Convert code text into searchable tokens.
+
+        Example:
+            "def getUserById(user_id):" -> ['get', 'user', 'by', 'id', 'user', 'id']
+        """
+        # Step 1: Split camelCase and PascalCase
+        # "getUserById" -> "get User By Id"
+        text = re.sub(r'([a-z])([A-Z])', r'\1 \2', text)
+
+        # Step 2: Split snake_case and other separators
+        # "get_user_by_id" -> "get user by id"
+        text = re.sub(r'[_\-./\\(){}[\]:,;"\']', ' ', text)
+
+        # Step 3: Lowercase and split into words
+        words = text.lower().split()
+
+        # Step 4: Remove stop words and very short tokens (1-2 chars)
+        tokens = [
+            word for word in words
+            if word not in self.STOP_WORDS and len(word) > 2
+        ]
+
+        return tokens
+
+
+class BM25Retriever:
+    """
+    BM25-based code search.
+
+    How it works:
+    1. Index: Convert each code chunk into tokens, build BM25 index
+    2. Search: Tokenize query, score each document, return top-K
+    """
+
+    def __init__(self):
+        self.tokenizer = CodeTokenizer()
+        self.documents = []      # List of original documents
+        self.doc_tokens = []     # List of tokenized documents
+        self.bm25 = None         # BM25 index (built after indexing)
+        self.doc_metadata = []   # Metadata for each document (file path, line numbers, etc.)
+
+    def index_documents(self, documents: List[Dict[str, Any]]) -> int:
+        """
+        Build BM25 index from code documents.
+
+        Args:
+            documents: List of dicts with 'content' and optional metadata
+                       Example: {'content': 'def get_user()...', 'file': 'users.py', 'type': 'function'}
+
+        Returns:
+            Number of documents indexed
+        """
+        self.documents = []
+        self.doc_tokens = []
+        self.doc_metadata = []
+
+        for doc in documents:
+            content = doc.get('content', '')
+
+            # Tokenize the content
+            tokens = self.tokenizer.tokenize(content)
+
+            # Only index if we got meaningful tokens
+            if tokens:
+                self.documents.append(content)
+                self.doc_tokens.append(tokens)
+                self.doc_metadata.append({
+                    'file': doc.get('file', 'unknown'),
+                    'name': doc.get('name', 'unknown'),
+                    'type': doc.get('type', 'unknown'),
+                    'start_line': doc.get('start_line', 0),
+                    'end_line': doc.get('end_line', 0)
+                })
+
+        # Build BM25 index from tokenized documents
+        if self.doc_tokens:
+            self.bm25 = BM25Okapi(self.doc_tokens)
+
+        return len(self.documents)
+
+    def search(self, query: str, top_k: int = 10) -> List[Dict[str, Any]]:
+        """
+        Search for relevant code using BM25 scoring.
+
+        Args:
+            query: Search query (natural language or code terms)
+            top_k: Number of results to return
+
+        Returns:
+            List of results with scores and metadata, sorted by relevance
+        """
+        if not self.bm25:
+            return []
+
+        # Tokenize the query the same way we tokenized documents
+        query_tokens = self.tokenizer.tokenize(query)
+
+        if not query_tokens:
+            return []
+
+        # Get BM25 scores for all documents
+        scores = self.bm25.get_scores(query_tokens)
+
+        # Get top-K document indices (sorted by score descending)
+        top_indices = sorted(
+            range(len(scores)),
+            key=lambda i: scores[i],
+            reverse=True
+        )[:top_k]
+
+        # Build results with scores and metadata
+        results = []
+        for rank, idx in enumerate(top_indices):
+            if scores[idx] > 0:  # Only include if there's some match
+                results.append({
+                    'rank': rank + 1,
+                    'score': float(scores[idx]),
+                    'content': self.documents[idx],
+                    **self.doc_metadata[idx]
+                })
+
+        return results
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about the index."""
+        if not self.doc_tokens:
+            return {'indexed': False}
+
+        total_tokens = sum(len(tokens) for tokens in self.doc_tokens)
+        avg_tokens = total_tokens / len(self.doc_tokens) if self.doc_tokens else 0
+
+        return {
+            'indexed': True,
+            'num_documents': len(self.documents),
+            'total_tokens': total_tokens,
+            'avg_tokens_per_doc': round(avg_tokens, 2)
+        }

codepilot/context/embedding_retriever.py

@@ -0,0 +1,185 @@
+"""
+Embedding Retriever - Semantic code search using vector embeddings
+
+How it works:
+1. Use a pre-trained model to convert code → vectors (embeddings)
+2. Store vectors in ChromaDB (a vector database)
+3. When searching, convert query → vector, find similar vectors
+
+This is the "semantic" half of our hybrid retrieval system.
+"""
+
+import os
+from typing import List, Dict, Any, Optional
+
+# ChromaDB for vector storage and similarity search
+import chromadb
+from chromadb.config import Settings
+
+# Sentence Transformers for creating embeddings
+# (Same pattern as our simple example: model.encode(text) → vector)
+from sentence_transformers import SentenceTransformer
+
+
+class EmbeddingRetriever:
+    """
+    Semantic search using vector embeddings.
+
+    Pattern from our example:
+        model.encode("login auth") → [0.2, 0.8, ...]
+
+    But instead of manual cosine_similarity, ChromaDB does it efficiently.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "all-MiniLM-L6-v2",
+        persist_directory: str = ".codepilot_cache/chromadb"
+    ):
+        """
+        Initialize the embedding retriever.
+
+        Args:
+            model_name: Which sentence-transformer model to use
+                        "all-MiniLM-L6-v2" is small (80MB) but effective
+            persist_directory: Where to save the vector database
+        """
+        # Load the pre-trained model (same as example: SentenceTransformer(...))
+        self.model = SentenceTransformer(model_name)
+
+        # Create ChromaDB client
+        # persist_directory means vectors are saved to disk (survives restarts)
+        os.makedirs(persist_directory, exist_ok=True)
+        self.client = chromadb.PersistentClient(path=persist_directory)
+
+        # Get or create a "collection" (like a table in a database)
+        # This is where we store our code vectors
+        self.collection = self.client.get_or_create_collection(
+            name="code_embeddings",
+            metadata={"description": "Code chunks for semantic search"}
+        )
+
+    def index_documents(self, documents: List[Dict[str, Any]]) -> int:
+        """
+        Convert code chunks to vectors and store in ChromaDB.
+
+        This is like our example:
+            vec = model.encode(text)
+        But we store many vectors at once in a database.
+
+        Args:
+            documents: List of dicts with 'content' and metadata
+                      Example: {'content': 'def login()...', 'file': 'auth.py'}
+
+        Returns:
+            Number of documents indexed
+        """
+        if not documents:
+            return 0
+
+        # Prepare data for ChromaDB
+        ids = []           # Unique ID for each document
+        texts = []         # The actual code content
+        metadatas = []     # Extra info (file path, line numbers, etc.)
+
+        for i, doc in enumerate(documents):
+            content = doc.get('content', '')
+            if not content.strip():
+                continue
+
+            # Create unique ID (ChromaDB requires string IDs)
+            doc_id = f"{doc.get('file', 'unknown')}::{doc.get('name', i)}"
+
+            ids.append(doc_id)
+            texts.append(content)
+            metadatas.append({
+                'file': doc.get('file', 'unknown'),
+                'name': doc.get('name', 'unknown'),
+                'type': doc.get('type', 'unknown'),
+                'start_line': doc.get('start_line', 0),
+                'end_line': doc.get('end_line', 0)
+            })
+
+        if not texts:
+            return 0
+
+        # Generate embeddings for all texts at once
+        # (Same as example: model.encode(text), but batched for efficiency)
+        embeddings = self.model.encode(texts, show_progress_bar=False)
+
+        # Store in ChromaDB
+        # ChromaDB handles: storing vectors, building search index, similarity math
+        self.collection.add(
+            ids=ids,
+            embeddings=embeddings.tolist(),  # ChromaDB wants Python lists
+            documents=texts,
+            metadatas=metadatas
+        )
+
+        return len(texts)
+
+    def search(self, query: str, top_k: int = 10) -> List[Dict[str, Any]]:
+        """
+        Find code semantically similar to the query.
+
+        This is like our example:
+            query_vec = model.encode(query)
+            similarity = cosine_similarity(query_vec, stored_vecs)
+        But ChromaDB does the similarity search efficiently.
+
+        Args:
+            query: Natural language or code description
+            top_k: Number of results to return
+
+        Returns:
+            List of results with similarity scores and metadata
+        """
+        # Convert query to vector (same as example: model.encode(...))
+        query_embedding = self.model.encode(query)
+
+        # ChromaDB finds the most similar stored vectors
+        # Internally, it computes cosine similarity against all stored vectors
+        results = self.collection.query(
+            query_embeddings=[query_embedding.tolist()],
+            n_results=top_k,
+            include=['documents', 'metadatas', 'distances']
+        )
+
+        # Format results
+        # Note: ChromaDB returns "distances" (lower = more similar)
+        # We convert to "scores" (higher = more similar) for consistency with BM25
+        formatted = []
+
+        if results['ids'] and results['ids'][0]:
+            for i, doc_id in enumerate(results['ids'][0]):
+                # Convert distance to similarity score (1 - distance for cosine)
+                distance = results['distances'][0][i]
+                similarity = 1 - distance  # Higher = more similar
+
+                formatted.append({
+                    'rank': i + 1,
+                    'score': float(similarity),
+                    'content': results['documents'][0][i],
+                    **results['metadatas'][0][i]
+                })
+
+        return formatted
+
+    def clear_index(self):
+        """Remove all documents from the index."""
+        # Delete and recreate the collection
+        self.client.delete_collection("code_embeddings")
+        self.collection = self.client.get_or_create_collection(
+            name="code_embeddings",
+            metadata={"description": "Code chunks for semantic search"}
+        )
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about the index."""
+        count = self.collection.count()
+        return {
+            'indexed': count > 0,
+            'num_documents': count,
+            'model': 'all-MiniLM-L6-v2',
+            'embedding_dimension': 384
+        }

codepilot/context/hybrid_retriever.py

@@ -0,0 +1,194 @@
+"""
+Hybrid Retriever - Combines BM25 and Embeddings using Reciprocal Rank Fusion
+
+RRF (Reciprocal Rank Fusion) solves the problem of merging ranked lists
+with different score scales by using ranks instead of raw scores.
+"""
+
+from typing import List, Dict, Any
+from codepilot.context.bm25_retriever import BM25Retriever
+from codepilot.context.embedding_retriever import EmbeddingRetriever
+
+
+class HybridRetriever:
+    """
+    Combines keyword search (BM25) and semantic search (Embeddings).
+
+    Why hybrid?
+    - BM25 finds exact matches (function names, variable names)
+    - Embeddings find semantic matches (related concepts)
+    - Together they cover both precision and recall
+    """
+
+    def __init__(self, bm25_weight: float = 0.5, embedding_weight: float = 0.5):
+        """
+        Initialize hybrid retriever with both search methods.
+
+        Args:
+            bm25_weight: Weight for BM25 scores (0-1, default 0.5)
+            embedding_weight: Weight for embedding scores (0-1, default 0.5)
+        """
+        # Create both retrievers
+        self.bm25 = BM25Retriever()
+        self.embeddings = EmbeddingRetriever()
+
+        # Weights (can be tuned based on your needs)
+        self.bm25_weight = bm25_weight
+        self.embedding_weight = embedding_weight
+
+        # RRF constant (k=60 is standard in literature)
+        self.k = 60
+
+    def index_documents(self, documents: List[Dict[str, Any]]) -> Dict[str, int]:
+        """
+        Index documents in BOTH retrievers.
+
+        This is the unified entry point - call this once and both
+        BM25 and Embeddings get indexed automatically.
+
+        Args:
+            documents: List of code chunks with metadata
+
+        Returns:
+            Statistics from both indexers
+        """
+        bm25_count = self.bm25.index_documents(documents)
+        embedding_count = self.embeddings.index_documents(documents)
+
+        return {
+            'bm25_indexed': bm25_count,
+            'embedding_indexed': embedding_count
+        }
+
+    def search(self, query: str, top_k: int = 10) -> List[Dict[str, Any]]:
+        """
+        Search using both BM25 and Embeddings, merge with RRF.
+
+        Process:
+        1. Get results from both retrievers
+        2. Convert to rank maps (doc_id → rank)
+        3. Calculate RRF score for each unique document
+        4. Sort by RRF score and return top K
+
+        Args:
+            query: Search query (natural language or code terms)
+            top_k: Number of final results to return
+
+        Returns:
+            Merged results sorted by RRF score
+        """
+        # Step 1: Get results from BOTH retrievers
+        # We fetch 2x top_k to have more candidates for fusion
+        bm25_results = self.bm25.search(query, top_k=top_k * 2)
+        embedding_results = self.embeddings.search(query, top_k=top_k * 2)
+
+        # Step 2: Build rank maps (document ID → rank position)
+        bm25_ranks = {}
+        for i, result in enumerate(bm25_results):
+            # Create unique ID from file + name
+            doc_id = f"{result['file']}::{result['name']}"
+            bm25_ranks[doc_id] = i + 1  # Ranks start at 1, not 0
+
+        embedding_ranks = {}
+        for i, result in enumerate(embedding_results):
+            doc_id = f"{result['file']}::{result['name']}"
+            embedding_ranks[doc_id] = i + 1
+
+        # Step 3: Collect ALL unique documents from both lists
+        all_doc_ids = set(bm25_ranks.keys()) | set(embedding_ranks.keys())
+
+        # Step 4: Calculate RRF score for each document
+        rrf_scores = {}
+        for doc_id in all_doc_ids:
+            score = 0.0
+
+            # Add BM25 contribution (if document appeared in BM25 results)
+            if doc_id in bm25_ranks:
+                # RRF formula: 1 / (k + rank)
+                score += self.bm25_weight * (1 / (self.k + bm25_ranks[doc_id]))
+
+            # Add Embedding contribution (if document appeared in Embedding results)
+            if doc_id in embedding_ranks:
+                score += self.embedding_weight * (1 / (self.k + embedding_ranks[doc_id]))
+
+            rrf_scores[doc_id] = score
+
+        # Step 5: Sort by RRF score (highest first) and take top K
+        sorted_doc_ids = sorted(
+            rrf_scores.keys(),
+            key=lambda doc_id: rrf_scores[doc_id],
+            reverse=True
+        )[:top_k]
+
+        # Step 6: Build final results with metadata
+        results = []
+        for rank, doc_id in enumerate(sorted_doc_ids):
+            # Get metadata from whichever retriever had this document
+            metadata = self._get_metadata(doc_id, bm25_results, embedding_results)
+
+            results.append({
+                'rank': rank + 1,
+                'rrf_score': round(rrf_scores[doc_id], 4),
+                'in_bm25': doc_id in bm25_ranks,
+                'in_embeddings': doc_id in embedding_ranks,
+                'bm25_rank': bm25_ranks.get(doc_id, None),
+                'embedding_rank': embedding_ranks.get(doc_id, None),
+                **metadata
+            })
+
+        return results
+
+    def _get_metadata(
+        self,
+        doc_id: str,
+        bm25_results: List[Dict],
+        embedding_results: List[Dict]
+    ) -> Dict[str, Any]:
+        """
+        Extract metadata for a document from whichever list contains it.
+
+        Args:
+            doc_id: Document identifier (file::name)
+            bm25_results: Results from BM25 search
+            embedding_results: Results from embedding search
+
+        Returns:
+            Metadata dict with file, name, content, etc.
+        """
+        # Try BM25 results first
+        for result in bm25_results:
+            if f"{result['file']}::{result['name']}" == doc_id:
+                return {
+                    'file': result['file'],
+                    'name': result['name'],
+                    'type': result.get('type', 'unknown'),
+                    'content': result.get('content', ''),
+                    'start_line': result.get('start_line', 0),
+                    'end_line': result.get('end_line', 0)
+                }
+
+        # Try embedding results
+        for result in embedding_results:
+            if f"{result['file']}::{result['name']}" == doc_id:
+                return {
+                    'file': result['file'],
+                    'name': result['name'],
+                    'type': result.get('type', 'unknown'),
+                    'content': result.get('content', ''),
+                    'start_line': result.get('start_line', 0),
+                    'end_line': result.get('end_line', 0)
+                }
+
+        # Shouldn't happen, but return empty dict as fallback
+        return {}
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics from both retrievers."""
+        return {
+            'bm25': self.bm25.get_stats(),
+            'embeddings': self.embeddings.get_stats(),
+            'weights': {
+                'bm25': self.bm25_weight,
+                'embeddings': self.embedding_weight
+            }
+        }

codepilot/context/indexer.py

@@ -0,0 +1,145 @@
+"""
+Codebase Indexer
+Scans entire project and builds searchable index of all Python files
+"""
+
+import os
+import json
+import hashlib
+from typing import Dict, List, Any, Optional
+from codepilot.context.parser import CodeParser
+
+
+class CodebaseIndexer:
+    """
+    Index an entire codebase for fast retrieval
+    """
+
+    def __init__(self, root_path: str, cache_dir: str = ".codepilot_cache"):
+        """
+        Initialize indexer
+
+        Args:
+            root_path: Root directory to index
+            cache_dir: Where to store cached index
+        """
+        self.root_path = root_path
+        self.cache_dir = cache_dir
+        self.parser = CodeParser()
+        self.index = {}  # file_path -> parsed_data
+
+    def build_index(self, file_extensions: List[str] = ['.py']) -> Dict[str, Any]:
+        """
+        Scan directory and index all matching files
+
+        Args:
+            file_extensions: List of extensions to index (default: ['.py'])
+
+        Returns:
+            Statistics about the indexing process
+        """
+        total_files = 0
+        total_functions = 0
+        total_classes = 0
+        errors = []
+
+        # Walk through directory tree
+        for root, dirs, files in os.walk(self.root_path):
+            # Skip unwanted directories (modify dirs in-place)
+            dirs[:] = [d for d in dirs if d not in [
+                '__pycache__', 'venv', 'node_modules', '.git',
+                '.pytest_cache', '.mypy_cache'
+            ]]
+
+            # Process each file
+            for file in files:
+                # Check if file has matching extension
+                if any(file.endswith(ext) for ext in file_extensions):
+                    file_path = os.path.join(root, file)
+
+                    # Parse the file
+                    result = self.parser.parse_file(file_path)
+
+                    if result.get('parse_errors'):
+                        errors.append({
+                            'file': file_path,
+                            'error': result['parse_errors'][0]
+                        })
+                    else:
+                        # Store in index
+                        self.index[file_path] = result
+                        total_files += 1
+                        total_functions += len(result.get('functions', []))
+                        total_classes += len(result.get('classes', []))
+
+        return {
+            'total_files': total_files,
+            'total_functions': total_functions,
+            'total_classes': total_classes,
+            'errors': errors
+        }
+
+    def find_definition(self, name: str) -> List[Dict[str, Any]]:
+        """
+        Find where a function or class is defined
+
+        Args:
+            name: Function or class name to search for
+
+        Returns:
+            List of locations where name is defined
+        """
+        results = []
+
+        for file_path, data in self.index.items():
+            # Check functions
+            for func in data.get('functions', []):
+                if func['name'] == name:
+                    results.append({
+                        'file': file_path,
+                        'line': func['start_line'],
+                        'type': 'function'
+                    })
+
+            # Check classes
+            for cls in data.get('classes', []):
+                if cls['name'] == name:
+                    results.append({
+                        'file': file_path,
+                        'line': cls['start_line'],
+                        'type': 'class'
+                    })
+
+        return results
+
+    def save_index(self, output_path: Optional[str] = None):
+        """
+        Save index to disk as JSON
+
+        Args:
+            output_path: Where to save (default: cache_dir/index.json)
+        """
+        if output_path is None:
+            # Create cache directory if it doesn't exist
+            os.makedirs(self.cache_dir, exist_ok=True)
+            output_path = os.path.join(self.cache_dir, 'index.json')
+
+        with open(output_path, 'w') as f:
+            json.dump(self.index, f, indent=2)
+
+        print(f"Index saved to {output_path}")
+
+    def load_index(self, input_path: Optional[str] = None):
+        """
+        Load index from disk
+
+        Args:
+            input_path: Where to load from (default: cache_dir/index.json)
+        """
+        if input_path is None:
+            input_path = os.path.join(self.cache_dir, 'index.json')
+
+        with open(input_path, 'r') as f:
+            self.index = json.load(f)
+
+        print(f"Index loaded from {input_path}")

codepilot/context/parser.py

@@ -0,0 +1,327 @@
+"""
+Python Code Parser using AST
+Extracts structured information from Python files
+"""
+
+import ast
+import os
+from typing import Dict, List, Any, Optional
+
+
+class CodeParser:
+    """
+    Parse Python code using AST to extract structured information
+    """
+
+    def parse_file(self, file_path: str) -> Dict[str, Any]:
+        """
+        Parse a Python file and extract all structural elements
+
+        Args:
+            file_path: Path to the Python file to parse
+
+        Returns:
+            Dictionary containing:
+            - file_path: str
+            - language: 'python'
+            - imports: List of import statements
+            - functions: List of function definitions
+            - classes: List of class definitions
+            - globals: List of global variables
+            - total_lines: int
+            - parse_errors: List of error messages (empty if successful)
+        """
+        try:
+            # Read the file
+            with open(file_path, 'r', encoding='utf-8') as f:
+                source_code = f.read()
+
+            # Count total lines
+            total_lines = len(source_code.split('\n'))
+
+            # Parse the AST
+            tree = ast.parse(source_code, filename=file_path)
+
+            # Extract elements
+            result = {
+                'file_path': file_path,
+                'language': 'python',
+                'imports': self._extract_imports(tree),
+                'functions': self._extract_functions(tree, source_code),
+                'classes': self._extract_classes(tree, source_code),
+                'globals': self._extract_globals(tree),
+                'total_lines': total_lines,
+                'parse_errors': []
+            }
+
+            return result
+
+        except FileNotFoundError:
+            return {
+                'file_path': file_path,
+                'parse_errors': [f"File not found: '{file_path}'"]
+            }
+        except SyntaxError as e:
+            return {
+                'file_path': file_path,
+                'parse_errors': [f"Syntax error at line {e.lineno}: {e.msg}"]
+            }
+        except Exception as e:
+            return {
+                'file_path': file_path,
+                'parse_errors': [f"Parse error: {str(e)}"]
+            }
+
+    def _extract_imports(self, tree: ast.AST) -> List[Dict[str, Any]]:
+        """Extract all import statements"""
+        imports = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.append({
+                        'name': alias.name,
+                        'alias': alias.asname,
+                        'line': node.lineno,
+                        'type': 'import'
+                    })
+            elif isinstance(node, ast.ImportFrom):
+                module = node.module or ''
+                for alias in node.names:
+                    imports.append({
+                        'name': f"{module}.{alias.name}" if module else alias.name,
+                        'module': module,
+                        'imported': alias.name,
+                        'alias': alias.asname,
+                        'line': node.lineno,
+                        'type': 'from'
+                    })
+
+        return imports
+
+    def _extract_functions(self, tree: ast.AST, source_code: str) -> List[Dict[str, Any]]:
+        """Extract all function definitions"""
+        functions = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef) or isinstance(node, ast.AsyncFunctionDef):
+                # Get function parameters
+                params = [arg.arg for arg in node.args.args]
+
+                # Get docstring
+                docstring = ast.get_docstring(node)
+
+                # Check if async
+                is_async = isinstance(node, ast.AsyncFunctionDef)
+
+                # Get decorators
+                decorators = [ast.unparse(dec) for dec in node.decorator_list]
+
+                functions.append({
+                    'name': node.name,
+                    'start_line': node.lineno,
+                    'end_line': node.end_lineno,
+                    'parameters': params,
+                    'docstring': docstring,
+                    'is_async': is_async,
+                    'decorators': decorators
+                })
+
+        return functions
+
+    def _extract_classes(self, tree: ast.AST, source_code: str) -> List[Dict[str, Any]]:
+        """Extract all class definitions"""
+        classes = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                # Get base classes
+                bases = [ast.unparse(base) for base in node.bases]
+
+                # Get docstring
+                docstring = ast.get_docstring(node)
+
+                # Get methods
+                methods = []
+                for item in node.body:
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        methods.append({
+                            'name': item.name,
+                            'is_async': isinstance(item, ast.AsyncFunctionDef),
+                            'line': item.lineno
+                        })
+
+                # Get decorators
+                decorators = [ast.unparse(dec) for dec in node.decorator_list]
+
+                classes.append({
+                    'name': node.name,
+                    'start_line': node.lineno,
+                    'end_line': node.end_lineno,
+                    'bases': bases,
+                    'docstring': docstring,
+                    'methods': methods,
+                    'decorators': decorators
+                })
+
+        return classes
+
+    def _extract_globals(self, tree: ast.AST) -> List[Dict[str, Any]]:
+        """Extract global variable assignments"""
+        globals_list = []
+
+        # Only look at module-level assignments
+        for node in tree.body if isinstance(tree, ast.Module) else []:
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        # Try to infer type from value
+                        value_type = self._infer_type(node.value)
+
+                        globals_list.append({
+                            'name': target.id,
+                            'line': node.lineno,
+                            'type': value_type
+                        })
+
+        return globals_list
+
+    def _infer_type(self, node: ast.AST) -> str:
+        """Infer type from AST node"""
+        if isinstance(node, ast.Constant):
+            return type(node.value).__name__
+        elif isinstance(node, ast.List):
+            return 'list'
+        elif isinstance(node, ast.Dict):
+            return 'dict'
+        elif isinstance(node, ast.Set):
+            return 'set'
+        elif isinstance(node, ast.Tuple):
+            return 'tuple'
+        elif isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name):
+                return node.func.id
+            return 'object'
+        else:
+            return 'unknown'
+
+    def extract_code_chunk(self, file_path: str, element_name: str) -> str:
+        """
+        Extract a specific function or class with its dependencies
+
+        Args:
+            file_path: Path to the Python file
+            element_name: Name of function or class to extract
+
+        Returns:
+            Complete code chunk including relevant imports and the element itself
+        """
+        try:
+            # Parse the file
+            result = self.parse_file(file_path)
+
+            if result.get('parse_errors'):
+                return f"Error: {result['parse_errors'][0]}"
+
+            # Read source code
+            with open(file_path, 'r', encoding='utf-8') as f:
+                lines = f.readlines()
+
+            # Find the element
+            element_lines = None
+
+            # Check functions
+            for func in result.get('functions', []):
+                if func['name'] == element_name:
+                    element_lines = (func['start_line'], func['end_line'])
+                    break
+
+            # Check classes
+            if not element_lines:
+                for cls in result.get('classes', []):
+                    if cls['name'] == element_name:
+                        element_lines = (cls['start_line'], cls['end_line'])
+                        break
+
+            if not element_lines:
+                return f"Error: '{element_name}' not found in {file_path}"
+
+            # Extract the code chunk
+            start_line, end_line = element_lines
+            chunk_lines = lines[start_line - 1:end_line]
+
+            # Add relevant imports at the beginning
+            import_lines = []
+            for imp in result.get('imports', []):
+                import_lines.append(lines[imp['line'] - 1])
+
+            # Combine imports and element code
+            if import_lines:
+                code_chunk = ''.join(import_lines) + '\n' + ''.join(chunk_lines)
+            else:
+                code_chunk = ''.join(chunk_lines)
+
+            return code_chunk.strip()
+
+        except FileNotFoundError:
+            return f"Error: File '{file_path}' not found."
+        except Exception as e:
+            return f"Error extracting code chunk: {str(e)}"
+
+    def get_file_summary(self, file_path: str) -> str:
+        """
+        Generate a concise summary of file contents
+
+        Args:
+            file_path: Path to the Python file
+
+        Returns:
+            Formatted summary string
+        """
+        try:
+            result = self.parse_file(file_path)
+
+            if result.get('parse_errors'):
+                return f"Error: {result['parse_errors'][0]}"
+
+            # Build summary
+            summary = []
+            summary.append(f"File: {file_path}")
+            summary.append(f"Lines: {result.get('total_lines', 0)}")
+
+            # Functions
+            functions = result.get('functions', [])
+            if functions:
+                func_names = ', '.join(f"{f['name']}()" for f in functions[:5])
+                if len(functions) > 5:
+                    func_names += f", ... ({len(functions) - 5} more)"
+                summary.append(f"Functions ({len(functions)}): {func_names}")
+
+            # Classes
+            classes = result.get('classes', [])
+            if classes:
+                class_names = ', '.join(c['name'] for c in classes[:3])
+                if len(classes) > 3:
+                    class_names += f", ... ({len(classes) - 3} more)"
+                summary.append(f"Classes ({len(classes)}): {class_names}")
+
+            # Imports
+            imports = result.get('imports', [])
+            if imports:
+                # Get unique module names
+                modules = set()
+                for imp in imports:
+                    if imp['type'] == 'import':
+                        modules.add(imp['name'].split('.')[0])
+                    else:
+                        modules.add(imp.get('module', '').split('.')[0] if imp.get('module') else imp['name'])
+
+                import_list = ', '.join(sorted(modules)[:5])
+                if len(modules) > 5:
+                    import_list += f", ... ({len(modules) - 5} more)"
+                summary.append(f"Imports: {import_list}")
+
+            return '\n'.join(summary)
+
+        except Exception as e:
+            return f"Error generating summary: {str(e)}"

codepilot/context/selector.py

@@ -0,0 +1,102 @@
+"""
+Context Selector
+Builds dependency graph and selects relevant code for LLM context
+"""
+
+import networkx as nx
+from codepilot.context.indexer import CodebaseIndexer
+
+
+class ContextSelector:
+    """
+    Select relevant code context based on dependencies
+    """
+
+    def __init__(self, indexer: CodebaseIndexer):
+        """
+        Initialize with a codebase indexer
+
+        Args:
+            indexer: CodebaseIndexer with already-built index
+        """
+        self.indexer = indexer          # Store the indexer (has all import data)
+        self.graph = nx.DiGraph()       # Create empty directed graph
+
+    def build_dependency_graph(self):
+        """
+        Build a directed graph where:
+        - Each node is a file
+        - Each edge A → B means "A imports from B"
+        """
+        # Loop through every file in the index
+        for file_path, data in self.indexer.index.items():
+
+            # Get imports for this file
+            imports = data['imports']
+
+            # Loop through each import
+            for imp in imports:
+                # Get the module name (e.g., 'codepilot.llm.client')
+                module_name = imp.get('module', '')
+
+                if module_name:
+                    # Convert to file path: 'codepilot.llm.client' → 'codepilot/llm/client.py'
+                    target_path = module_name.replace('.', '/') + '.py'
+
+                    # Check if this file exists in our index
+                    # (we only care about files in our project, not external like 'os' or 'json')
+                    for indexed_file in self.indexer.index.keys():
+                        if indexed_file.endswith(target_path):
+                            # Add edge: file_path depends on indexed_file
+                            self.graph.add_edge(file_path, indexed_file)
+                            break
+
+        print(f"Graph built: {self.graph.number_of_nodes()} files, {self.graph.number_of_edges()} dependencies")
+
+    def get_dependencies(self, file_path: str) -> list:
+        """
+        Get all files that this file imports from
+
+        Args:
+            file_path: The file to check
+
+        Returns:
+            List of file paths that this file depends on
+        """
+        if file_path not in self.graph:
+            return []
+        return list(self.graph.successors(file_path))
+
+    def get_dependents(self, file_path: str) -> list:
+        """
+        Get all files that import from this file
+
+        Args:
+            file_path: The file to check
+
+        Returns:
+            List of file paths that depend on this file
+        """
+        if file_path not in self.graph:
+            return []
+        return list(self.graph.predecessors(file_path))
+
+    def get_related_files(self, file_path: str) -> list:
+        """
+        Get all files related to this file (both directions)
+
+        Args:
+            file_path: The file to check
+
+        Returns:
+            List of all related file paths
+        """
+        related = set()  # Use set to avoid duplicates
+
+        # Files this one depends on
+        related.update(self.get_dependencies(file_path))
+
+        # Files that depend on this one
+        related.update(self.get_dependents(file_path))
+
+        return list(related)

codepilot/llm/client.py

@@ -0,0 +1,84 @@
+"""
+OpenAI Client Wrapper
+Handles all communication with OpenAI's API
+"""
+
+import os
+from dotenv import load_dotenv
+import openai
+from typing import List, Dict, Optional
+
+load_dotenv()
+
+
+class OpenAIClient:
+    """Wrapper for OpenAI API calls"""
+
+    def __init__(self, model: str = "gpt-3.5-turbo"):
+        """
+        Initialize OpenAI client
+
+        Args:
+            model: OpenAI model to use (default: gpt-3.5-turbo)
+        """
+        self.api_key = os.getenv('OPENAI_API_KEY')
+
+        if not self.api_key:
+            raise ValueError("OPENAI_API_KEY not found in environment variables")
+
+        self.client = openai.OpenAI(api_key=self.api_key)
+        self.model = model
+
+        print(f"✅ OpenAI Client initialized with model: {self.model}")
+
+    def chat(
+        self,
+        messages: List[Dict[str, str]],
+        tools: Optional[List[Dict]] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 2000
+    ) -> openai.types.chat.ChatCompletion:
+        """
+        Send a chat completion request to OpenAI
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            tools: Optional list of tool definitions for function calling
+            temperature: Randomness (0-2, lower = more focused)
+            max_tokens: Maximum tokens in response
+
+        Returns:
+            OpenAI ChatCompletion response object
+        """
+        try:
+            # Build request parameters
+            request_params = {
+                "model": self.model,
+                "messages": messages,
+                "temperature": temperature,
+                "max_tokens": max_tokens
+            }
+
+            # Add tools if provided
+            if tools:
+                request_params["tools"] = tools
+                request_params["tool_choice"] = "auto"
+
+            # Make API call
+            response = self.client.chat.completions.create(**request_params)
+
+            # Print token usage for cost tracking
+            usage = response.usage
+            print(f"📊 Tokens: {usage.prompt_tokens} prompt + {usage.completion_tokens} completion = {usage.total_tokens} total")
+
+            return response
+
+        except openai.APIError as e:
+            print(f"❌ OpenAI API Error: {e}")
+            raise
+        except openai.RateLimitError as e:
+            print(f"❌ Rate Limit Error: {e}")
+            raise
+        except Exception as e:
+            print(f"❌ Unexpected Error: {e}")
+            raise

codepilot/sandbox/__init__.py

@@ -0,0 +1,5 @@
+"""
+E2B Sandbox Integration
+
+Provides safe, isolated code execution for AI agents.
+"""

codepilot/sandbox/e2b_sandbox.py

@@ -0,0 +1,213 @@
+"""
+E2B Sandbox Manager
+
+Manages lifecycle of E2B sandboxes for safe code execution.
+"""
+
+from e2b_code_interpreter.code_interpreter_sync import Sandbox
+from typing import Dict, Any, Optional
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+class E2BSandboxManager:
+    """
+    Manages E2B sandbox instances for isolated code execution.
+
+    The sandbox provides:
+    - Isolated filesystem (files don't affect host)
+    - Safe execution (code can't access host system)
+    - Clean environment (starts fresh each time)
+    """
+
+    def __init__(self):
+        """
+        Initialize sandbox manager.
+
+        E2B API key is read from E2B_API_KEY environment variable.
+        """
+        if not os.getenv("E2B_API_KEY"):
+            raise ValueError("E2B_API_KEY not found in environment variables")
+
+        self.sandbox: Optional[Sandbox] = None
+        self._is_open = False
+
+    def create(self) -> str:
+        """
+        Create a new sandbox instance.
+
+        Returns:
+            Sandbox ID
+        """
+        if self._is_open:
+            return f"Sandbox already running (ID: {self.sandbox.sandbox_id})"
+
+        try:
+            api_key = os.getenv("E2B_API_KEY")
+            self.sandbox = Sandbox.create(api_key=api_key)
+            self._is_open = True
+            return f"✅ Sandbox created (ID: {self.sandbox.sandbox_id})"
+        except Exception as e:
+            return f"❌ Error creating sandbox: {str(e)}"
+
+    def close(self) -> str:
+        """
+        Close and destroy the sandbox.
+
+        Returns:
+            Success message
+        """
+        if not self._is_open:
+            return "No sandbox to close"
+
+        try:
+            if self.sandbox:
+                self.sandbox.kill()
+            self._is_open = False
+            return "✅ Sandbox closed"
+        except Exception as e:
+            return f"❌ Error closing sandbox: {str(e)}"
+
+    def upload_file(self, path: str, content: str) -> str:
+        """
+        Upload a file to the sandbox.
+
+        Args:
+            path: Path in sandbox where file should be written
+            content: File content
+
+        Returns:
+            Success or error message
+        """
+        if not self._is_open:
+            return "❌ No sandbox running. Create one first."
+
+        try:
+            self.sandbox.files.write(path, content)
+            return f"✅ Uploaded file to sandbox: {path} ({len(content)} chars)"
+        except Exception as e:
+            return f"❌ Error uploading file: {str(e)}"
+
+    def run_code(self, code: str, language: str = "python") -> Dict[str, Any]:
+        """
+        Execute code in the sandbox.
+
+        Args:
+            code: Code to execute
+            language: Programming language (default: python)
+
+        Returns:
+            Dict with stdout, stderr, exit_code, and error (if any)
+        """
+        if not self._is_open:
+            return {
+                "stdout": "",
+                "stderr": "❌ No sandbox running. Create one first.",
+                "exit_code": 1,
+                "error": "No sandbox"
+            }
+
+        try:
+            # Execute code in sandbox
+            execution = self.sandbox.run_code(code)
+
+            return {
+                "stdout": execution.text or "",
+                "stderr": execution.error or "",
+                "exit_code": 0 if not execution.error else 1,
+                "error": None
+            }
+        except Exception as e:
+            return {
+                "stdout": "",
+                "stderr": str(e),
+                "exit_code": 1,
+                "error": str(e)
+            }
+
+    def run_command(self, command: str) -> Dict[str, Any]:
+        """
+        Run a shell command in the sandbox.
+
+        Args:
+            command: Shell command to execute
+
+        Returns:
+            Dict with stdout, stderr, exit_code
+        """
+        if not self._is_open:
+            return {
+                "stdout": "",
+                "stderr": "❌ No sandbox running. Create one first.",
+                "exit_code": 1
+            }
+
+        try:
+            # Run shell command
+            process = self.sandbox.commands.run(command)
+
+            return {
+                "stdout": process.stdout,
+                "stderr": process.stderr,
+                "exit_code": process.exit_code
+            }
+        except Exception as e:
+            return {
+                "stdout": "",
+                "stderr": str(e),
+                "exit_code": 1
+            }
+
+    def list_files(self, path: str = ".") -> str:
+        """
+        List files in sandbox directory.
+
+        Args:
+            path: Directory path to list
+
+        Returns:
+            List of files as string
+        """
+        if not self._is_open:
+            return "❌ No sandbox running. Create one first."
+
+        try:
+            result = self.sandbox.commands.run(f"ls -la {path}")
+            return result.stdout
+        except Exception as e:
+            return f"❌ Error listing files: {str(e)}"
+
+    def read_file(self, path: str) -> str:
+        """
+        Read a file from the sandbox.
+
+        Args:
+            path: File path in sandbox
+
+        Returns:
+            File contents or error message
+        """
+        if not self._is_open:
+            return "❌ No sandbox running. Create one first."
+
+        try:
+            content = self.sandbox.files.read(path)
+            return content
+        except Exception as e:
+            return f"❌ Error reading file: {str(e)}"
+
+    def is_running(self) -> bool:
+        """Check if sandbox is currently running."""
+        return self._is_open
+
+    def __enter__(self):
+        """Context manager support: with E2BSandboxManager() as sandbox:"""
+        self.create()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager support: automatically close on exit"""
+        self.close()

codepilot/sandbox/sandbox_tools.py

@@ -0,0 +1,184 @@
+"""
+Sandbox Tools for AI Agents
+
+These tools allow agents to safely execute code in isolated environments.
+"""
+
+from codepilot.sandbox.e2b_sandbox import E2BSandboxManager
+from typing import Dict, Any
+
+# Global sandbox instance (shared across tool calls)
+_sandbox_manager: E2BSandboxManager = None
+
+
+def create_sandbox() -> str:
+    """
+    Create a new E2B sandbox for code execution.
+
+    Returns:
+        Success message with sandbox ID
+    """
+    global _sandbox_manager
+
+    try:
+        _sandbox_manager = E2BSandboxManager()
+        return _sandbox_manager.create()
+    except Exception as e:
+        return f"❌ Failed to create sandbox: {str(e)}"
+
+
+def close_sandbox() -> str:
+    """
+    Close and destroy the current sandbox.
+
+    Returns:
+        Success message
+    """
+    global _sandbox_manager
+
+    if _sandbox_manager is None:
+        return "No sandbox to close"
+
+    result = _sandbox_manager.close()
+    _sandbox_manager = None
+    return result
+
+
+def upload_to_sandbox(path: str, content: str) -> str:
+    """
+    Upload a file to the sandbox.
+
+    Args:
+        path: Path where file should be written in sandbox (e.g., "test.py")
+        content: File content to upload
+
+    Returns:
+        Success or error message
+    """
+    global _sandbox_manager
+
+    if _sandbox_manager is None or not _sandbox_manager.is_running():
+        # Auto-create sandbox if it doesn't exist
+        create_result = create_sandbox()
+        if "❌" in create_result:
+            return create_result
+
+    return _sandbox_manager.upload_file(path, content)
+
+
+def execute_in_sandbox(code: str) -> str:
+    """
+    Execute Python code in the sandbox.
+
+    Args:
+        code: Python code to execute
+
+    Returns:
+        Formatted output with stdout and stderr
+    """
+    global _sandbox_manager
+
+    if _sandbox_manager is None or not _sandbox_manager.is_running():
+        # Auto-create sandbox if it doesn't exist
+        create_result = create_sandbox()
+        if "❌" in create_result:
+            return create_result
+
+    result = _sandbox_manager.run_code(code)
+
+    # Format the output nicely
+    output = []
+    if result["stdout"]:
+        output.append(f"📤 Output:\n{result['stdout']}")
+    if result["stderr"]:
+        output.append(f"⚠️  Errors:\n{result['stderr']}")
+    if result.get("error"):
+        output.append(f"❌ Error: {result['error']}")
+
+    return "\n\n".join(output) if output else "✅ Code executed successfully (no output)"
+
+
+def run_command_in_sandbox(command: str) -> str:
+    """
+    Run a shell command in the sandbox.
+
+    Args:
+        command: Shell command to execute (e.g., "python test.py", "pytest")
+
+    Returns:
+        Command output
+    """
+    global _sandbox_manager
+
+    if _sandbox_manager is None or not _sandbox_manager.is_running():
+        # Auto-create sandbox if it doesn't exist
+        create_result = create_sandbox()
+        if "❌" in create_result:
+            return create_result
+
+    result = _sandbox_manager.run_command(command)
+
+    # Format the output
+    output = []
+    if result["stdout"]:
+        output.append(f"📤 Output:\n{result['stdout']}")
+    if result["stderr"]:
+        output.append(f"⚠️  Errors:\n{result['stderr']}")
+    if result["exit_code"] != 0:
+        output.append(f"❌ Exit code: {result['exit_code']}")
+
+    return "\n\n".join(output) if output else "✅ Command executed successfully (no output)"
+
+
+def list_sandbox_files(path: str = ".") -> str:
+    """
+    List files in the sandbox directory.
+
+    Args:
+        path: Directory path to list (default: current directory)
+
+    Returns:
+        List of files
+    """
+    global _sandbox_manager
+
+    if _sandbox_manager is None or not _sandbox_manager.is_running():
+        return "❌ No sandbox running. Create one first."
+
+    return _sandbox_manager.list_files(path)
+
+
+def read_sandbox_file(path: str) -> str:
+    """
+    Read a file from the sandbox.
+
+    Args:
+        path: File path in sandbox
+
+    Returns:
+        File contents
+    """
+    global _sandbox_manager
+
+    if _sandbox_manager is None or not _sandbox_manager.is_running():
+        return "❌ No sandbox running. Create one first."
+
+    return _sandbox_manager.read_file(path)
+
+
+# Helper function to get current sandbox status
+def get_sandbox_status() -> str:
+    """
+    Get the current sandbox status.
+
+    Returns:
+        Status message
+    """
+    global _sandbox_manager
+
+    if _sandbox_manager is None:
+        return "No sandbox created"
+    elif _sandbox_manager.is_running():
+        return f"✅ Sandbox running (ID: {_sandbox_manager.sandbox.id})"
+    else:
+        return "Sandbox closed"

codepilot/tools/context_tools.py

@@ -0,0 +1,143 @@
+"""
+Context Tools
+Tools that use the codebase index and dependency graph
+"""
+
+from codepilot.context.indexer import CodebaseIndexer
+from codepilot.context.selector import ContextSelector
+from codepilot.context.hybrid_retriever import HybridRetriever
+from typing import List, Dict, Any
+
+# Global instances (set when index_codebase is called)
+_indexer = None
+_selector = None
+_hybrid_retriever = None  # Will hold our search engine
+
+
+def index_codebase(path: str = ".") -> str:
+    """
+    Index a codebase to enable context-aware tools.
+
+    This builds THREE indexes:
+    1. CodebaseIndexer - AST-based parsing of all files
+    2. ContextSelector - Dependency graph
+    3. HybridRetriever - BM25 + Embeddings for search
+
+    Args:
+        path: Root directory to index (default: current directory)
+
+    Returns:
+        Summary of what was indexed
+    """
+    global _indexer, _selector, _hybrid_retriever
+
+    # Step 1: Create indexer and build AST index
+    _indexer = CodebaseIndexer(path)
+    stats = _indexer.build_index()
+
+    # Step 2: Create selector and build dependency graph
+    _selector = ContextSelector(_indexer)
+    _selector.build_dependency_graph()
+
+    # Step 3: Build hybrid retriever index
+    # Convert indexed data to documents for retrieval
+    documents = []
+    for file_path, file_data in _indexer.index.items():
+        # Read the source file to extract code snippets
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                source_lines = f.readlines()
+        except:
+            continue  # Skip if file can't be read
+
+        # Add each function as a searchable document
+        for func in file_data.get('functions', []):
+            start = func.get('start_line', 1) - 1  # Convert to 0-indexed
+            end = func.get('end_line', start + 1)
+
+            # Extract code lines
+            code = ''.join(source_lines[start:end])
+
+            if code.strip():  # Only add if we got code
+                documents.append({
+                    'content': code,
+                    'file': file_path,
+                    'name': func['name'],
+                    'type': 'function',
+                    'start_line': func.get('start_line', 0),
+                    'end_line': func.get('end_line', 0)
+                })
+
+        # Add each class as a searchable document
+        for cls in file_data.get('classes', []):
+            start = cls.get('start_line', 1) - 1
+            end = cls.get('end_line', start + 1)
+
+            code = ''.join(source_lines[start:end])
+
+            if code.strip():
+                documents.append({
+                    'content': code,
+                    'file': file_path,
+                    'name': cls['name'],
+                    'type': 'class',
+                    'start_line': cls.get('start_line', 0),
+                    'end_line': cls.get('end_line', 0)
+                })
+
+    # Create and index hybrid retriever
+    _hybrid_retriever = HybridRetriever()
+    retrieval_stats = _hybrid_retriever.index_documents(documents)
+
+    # Return summary
+    return (
+        f"Indexed {stats['total_files']} files, "
+        f"{stats['total_functions']} functions, "
+        f"{stats['total_classes']} classes. "
+        f"Dependency graph: {_selector.graph.number_of_edges()} connections. "
+        f"Hybrid retriever: {retrieval_stats['bm25_indexed']} BM25 docs, "
+        f"{retrieval_stats['embedding_indexed']} embedding docs."
+    )
+
+
+def search_codebase(query: str, top_k: int = 5) -> str:
+    """
+    Search the codebase using hybrid retrieval (BM25 + embeddings).
+
+    Uses both keyword matching and semantic search to find relevant code.
+
+    Args:
+        query: What to search for (e.g., "authentication logic", "error handling")
+        top_k: Number of results to return (default: 5)
+
+    Returns:
+        Formatted string with search results including file paths, function names, and code snippets
+    """
+    global _hybrid_retriever
+
+    # Check if index is built
+    if _hybrid_retriever is None:
+        return "Error: Codebase not indexed. Call index_codebase() first."
+
+    # Perform hybrid search
+    results = _hybrid_retriever.search(query, top_k=top_k)
+
+    if not results:
+        return f"No results found for query: '{query}'"
+
+    # Format results for the agent
+    output = [f"Found {len(results)} results for '{query}':\n"]
+
+    for result in results:
+        output.append(f"\n[{result['rank']}] {result['type']}: {result['name']}")
+        output.append(f"    File: {result['file']}:{result['start_line']}")
+        output.append(f"    Score: {result['rrf_score']:.4f}")
+        output.append(f"    In BM25: {result['in_bm25']}, In Embeddings: {result['in_embeddings']}")
+
+        # Show code snippet (first 3 lines)
+        code_lines = result['content'].split('\n')[:3]
+        output.append(f"    Code preview:")
+        for line in code_lines:
+            output.append(f"      {line}")
+
+    return '\n'.join(output)

codepilot/tools/file_tools.py

@@ -0,0 +1,255 @@
+"""
+File operation tools for the agent
+"""
+
+import subprocess
+import os
+
+
+def read_file(path):
+    """
+    Reads and returns the contents of a file.
+
+    Args:
+        path: File path to read
+
+    Returns:
+        str: File contents or error message
+    """
+    try:
+        with open(path, 'r') as f:
+            content = f.read()
+        return f"Successfully read file '{path}':\n\n{content}"
+    except FileNotFoundError:
+        return f"Error: File '{path}' not found."
+    except PermissionError:
+        return f"Error: Permission denied to read file '{path}'."
+    except Exception as e:
+        return f"Error reading file '{path}': {str(e)}"
+
+
+def write_file(path, content):
+    """
+    Writes content to a file, creating it if it doesn't exist.
+
+    Args:
+        path: File path to write to
+        content: Content to write
+
+    Returns:
+        str: Success or error message
+    """
+    try:
+        # Create directory if it doesn't exist
+        directory = os.path.dirname(path)
+        if directory and not os.path.exists(directory):
+            os.makedirs(directory)
+
+        with open(path, 'w') as f:
+            f.write(content)
+
+        return f"Successfully wrote {len(content)} characters to '{path}'."
+    except PermissionError:
+        return f"Error: Permission denied to write to '{path}'."
+    except Exception as e:
+        return f"Error writing to file '{path}': {str(e)}"
+
+
+def run_command(command):
+    """
+    Executes a shell command and returns the output.
+
+    Args:
+        command: Shell command to execute
+
+    Returns:
+        str: Command output or error message
+    """
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        output = []
+        if result.stdout:
+            output.append(f"Output:\n{result.stdout}")
+        if result.stderr:
+            output.append(f"Errors:\n{result.stderr}")
+
+        status = "succeeded" if result.returncode == 0 else f"failed (exit code {result.returncode})"
+        output.insert(0, f"Command '{command}' {status}.")
+
+        return "\n\n".join(output)
+
+    except subprocess.TimeoutExpired:
+        return f"Error: Command '{command}' timed out after 30 seconds."
+    except Exception as e:
+        return f"Error executing command '{command}': {str(e)}"
+
+
+def search_code(pattern, path=".", file_extension=None):
+    """
+    Search for a pattern in code files (like grep).
+
+    Args:
+        pattern: Text pattern to search for
+        path: Directory to search in (default: current directory)
+        file_extension: Optional file extension filter (e.g., "py", "js")
+
+    Returns:
+        str: Search results or error message
+    """
+    try:
+        # Build grep command
+        cmd_parts = ["grep", "-r", "-n", "-i", pattern, path]
+
+        # Add file extension filter if specified
+        if file_extension:
+            # Remove leading dot if present
+            ext = file_extension.lstrip('.')
+            cmd_parts.extend(["--include", f"*.{ext}"])
+
+        # Exclude common directories
+        cmd_parts.extend([
+            "--exclude-dir=venv",
+            "--exclude-dir=node_modules",
+            "--exclude-dir=__pycache__",
+            "--exclude-dir=.git"
+        ])
+
+        result = subprocess.run(
+            cmd_parts,
+            capture_output=True,
+            text=True,
+            timeout=10
+        )
+
+        if result.returncode == 0:
+            lines = result.stdout.strip().split('\n')
+            # Limit results to prevent overwhelming output
+            if len(lines) > 50:
+                return f"Found {len(lines)} matches (showing first 50):\n\n" + '\n'.join(lines[:50])
+            else:
+                return f"Found {len(lines)} matches:\n\n{result.stdout}"
+        elif result.returncode == 1:
+            return f"No matches found for pattern '{pattern}' in {path}"
+        else:
+            return f"Error searching: {result.stderr}"
+
+    except subprocess.TimeoutExpired:
+        return f"Error: Search timed out after 10 seconds."
+    except Exception as e:
+        return f"Error searching for pattern '{pattern}': {str(e)}"
+
+
+def list_files(path=".", pattern=None, show_hidden=False):
+    """
+    List files and directories.
+
+    Args:
+        path: Directory path to list (default: current directory)
+        pattern: Optional glob pattern to filter (e.g., "*.py", "test_*")
+        show_hidden: Whether to show hidden files (default: False)
+
+    Returns:
+        str: List of files or error message
+    """
+    try:
+        import glob
+
+        # Build the search pattern
+        if pattern:
+            search_path = os.path.join(path, pattern)
+        else:
+            search_path = os.path.join(path, "*")
+
+        # Get all matches
+        matches = glob.glob(search_path)
+
+        # Filter hidden files if needed
+        if not show_hidden:
+            matches = [m for m in matches if not os.path.basename(m).startswith('.')]
+
+        if not matches:
+            return f"No files found in '{path}'" + (f" matching '{pattern}'" if pattern else "")
+
+        # Separate files and directories
+        files = []
+        dirs = []
+
+        for item in sorted(matches):
+            rel_path = os.path.relpath(item, path)
+            if os.path.isdir(item):
+                dirs.append(f"📁 {rel_path}/")
+            else:
+                size = os.path.getsize(item)
+                files.append(f"📄 {rel_path} ({size} bytes)")
+
+        result = []
+        result.append(f"Contents of '{path}':")
+        if pattern:
+            result.append(f"(filtered by: {pattern})")
+        result.append("")
+
+        if dirs:
+            result.append("Directories:")
+            result.extend(dirs)
+            result.append("")
+
+        if files:
+            result.append("Files:")
+            result.extend(files)
+
+        result.append(f"\nTotal: {len(dirs)} directories, {len(files)} files")
+
+        return "\n".join(result)
+
+    except Exception as e:
+        return f"Error listing files in '{path}': {str(e)}"
+
+
+def git_status():
+    """
+    Get git repository status.
+
+    Returns:
+        str: Git status output or error message
+    """
+    try:
+        # Check if we're in a git repo
+        check_result = subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+
+        if check_result.returncode != 0:
+            return "Not a git repository"
+
+        # Get status
+        result = subprocess.run(
+            ["git", "status", "--short", "--branch"],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+
+        if result.returncode == 0:
+            if result.stdout.strip():
+                return f"Git Status:\n\n{result.stdout}"
+            else:
+                return "Git Status: Working tree clean (no changes)"
+        else:
+            return f"Error getting git status: {result.stderr}"
+
+    except subprocess.TimeoutExpired:
+        return "Error: Git command timed out"
+    except FileNotFoundError:
+        return "Error: Git is not installed"
+    except Exception as e:
+        return f"Error checking git status: {str(e)}"

codepilot/tools/registry.py

@@ -0,0 +1,278 @@
+"""
+Tool Registry
+Maps tool names to their implementations and schemas
+"""
+
+import os
+from codepilot.tools.file_tools import read_file, write_file, run_command, search_code, list_files, git_status
+from codepilot.sandbox.sandbox_tools import (
+    create_sandbox,
+    close_sandbox,
+    upload_to_sandbox,
+    execute_in_sandbox,
+    run_command_in_sandbox
+)
+from typing import Callable, List, Dict, Optional
+
+# Check if running in production BEFORE importing heavy ML dependencies
+# Detects: Render, HuggingFace Spaces, or any cloud with PORT env var
+_IS_PRODUCTION = os.getenv('RENDER_SERVICE_NAME') or os.getenv('RENDER') or os.getenv('SPACE_ID') or os.getenv('PORT')
+
+# Only import heavy context_tools (sentence-transformers, torch) in local development
+if not _IS_PRODUCTION:
+    from codepilot.tools.context_tools import search_codebase, index_codebase
+else:
+    # Provide stub functions for production to avoid import errors
+    def search_codebase(query: str, top_k: int = 5) -> str:
+        return "⚠️ Codebase search is disabled in cloud mode (resource constraints)"
+
+    def index_codebase(root_path: str) -> str:
+        return "⚠️ Codebase indexing is disabled in cloud mode (resource constraints)"
+
+
+# Tool schemas for OpenAI function calling
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Reads the contents of a file at the specified path. Use this when you need to view or analyze file contents.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "The file path to read (absolute or relative path)"
+                    }
+                },
+                "required": ["path"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Writes content to a file at the specified path. Creates the file if it doesn't exist, overwrites if it does. Use this when you need to create or modify files.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "The file path to write to (absolute or relative path)"
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "The content to write to the file"
+                    }
+                },
+                "required": ["path", "content"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "run_command",
+            "description": "Executes a shell command in the system terminal. Use this for running scripts, installing packages, or executing system commands.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "The shell command to execute"
+                    }
+                },
+                "required": ["command"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "search_code",
+            "description": "Search for a text pattern in code files (like grep). Use this to find where functions, classes, or text appears in the codebase.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "The text pattern to search for"
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Directory to search in (default: current directory)"
+                    },
+                    "file_extension": {
+                        "type": "string",
+                        "description": "Optional file extension filter (e.g., 'py', 'js')"
+                    }
+                },
+                "required": ["pattern"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_files",
+            "description": "List files and directories in a path. Use this to explore the project structure or find files.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Directory path to list (default: current directory)"
+                    },
+                    "pattern": {
+                        "type": "string",
+                        "description": "Optional glob pattern to filter files (e.g., '*.py', 'test_*')"
+                    },
+                    "show_hidden": {
+                        "type": "boolean",
+                        "description": "Whether to show hidden files (default: false)"
+                    }
+                },
+                "required": []
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "git_status",
+            "description": "Get the git repository status. Use this to see what files have been modified, added, or deleted.",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+                "required": []
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "search_codebase",
+            "description": "Search the codebase using hybrid retrieval (combines keyword matching with semantic search). More powerful than search_code - finds both exact matches AND semantically related code. Use this when looking for specific functionality, patterns, or concepts in the codebase.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "What to search for. Can be natural language (e.g., 'authentication logic', 'error handling') or specific terms (e.g., 'login function', 'database connection')"
+                    },
+                    "top_k": {
+                        "type": "integer",
+                        "description": "Number of results to return (default: 5, max: 20)",
+                        "default": 5
+                    }
+                },
+                "required": ["query"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "upload_to_sandbox",
+            "description": "Upload a file to the E2B sandbox for safe execution. Use this BEFORE running code to ensure the file exists in the sandbox environment.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "File path in sandbox (e.g., 'test.py', 'utils/helper.py')"
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "File content to upload"
+                    }
+                },
+                "required": ["path", "content"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "run_command_in_sandbox",
+            "description": "Run a shell command in the isolated E2B sandbox. Use this to safely execute code, run tests, or perform system operations without affecting the host system. Examples: 'python test.py', 'pytest', 'npm test'.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Shell command to execute in sandbox"
+                    }
+                },
+                "required": ["command"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_in_sandbox",
+            "description": "Execute Python code directly in the E2B sandbox. Use for quick code testing or running Python snippets without creating files.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "code": {
+                        "type": "string",
+                        "description": "Python code to execute"
+                    }
+                },
+                "required": ["code"]
+            }
+        }
+    }
+]
+
+
+# Map tool names to their implementation functions
+TOOL_FUNCTIONS = {
+    "read_file": read_file,
+    "write_file": write_file,
+    "run_command": run_command,
+    "search_code": search_code,
+    "list_files": list_files,
+    "git_status": git_status,
+    "search_codebase": search_codebase,
+    "index_codebase": index_codebase,
+    "upload_to_sandbox": upload_to_sandbox,
+    "execute_in_sandbox": execute_in_sandbox,
+    "run_command_in_sandbox": run_command_in_sandbox
+}
+
+
+def get_tools() -> List[Dict]:
+    """
+    Get all available tool schemas
+
+    Returns:
+        List of tool schema dictionaries for OpenAI
+    """
+    return TOOLS
+
+
+def get_tool_function(tool_name: str) -> Optional[Callable]:
+    """
+    Get the implementation function for a tool by name
+
+    Args:
+        tool_name: Name of the tool (e.g., "read_file")
+
+    Returns:
+        The tool function, or None if not found
+    """
+    return TOOL_FUNCTIONS.get(tool_name)
+
+
+def list_tool_names() -> List[str]:
+    """
+    Get list of all available tool names
+
+    Returns:
+        List of tool name strings
+    """
+    return list(TOOL_FUNCTIONS.keys())

requirements.txt

@@ -0,0 +1,22 @@
+# Cloud deployment requirements (lightweight - no PyTorch/sentence-transformers)
+# These are only the essential packages needed for HuggingFace Spaces
+
+# Core
+openai>=1.0.0
+python-dotenv>=1.2.0
+
+# E2B Sandbox
+e2b-code-interpreter>=2.4.0
+
+# LangChain (minimal)
+langchain>=0.3.0
+langgraph>=0.2.0
+
+# Lightweight search (no embeddings in cloud mode)
+rank-bm25>=0.2.2
+
+# Chainlit UI
+chainlit>=1.0.0
+
+# For dependency graphs
+networkx>=3.0