🤖 CodeBuddy - AI Coding Agent

An AI-powered coding agent that generates complete projects from natural language prompts. CodeBuddy uses a multi-agent workflow (Planner → Architect → Coder) to understand your requirements and automatically generate production-ready code.

✨ Features

• Multi-Agent Architecture: Three specialized agents work together:

  • Planner: Analyzes your prompt and creates a structured project plan
  • Architect: Breaks down the plan into ordered implementation tasks
  • Coder: Implements each task using file system tools

• Web Interface: Beautiful Streamlit-based UI for easy interaction

• CLI Support: Command-line interface for automation and scripting

• Safe File Operations: All file operations are restricted to the project directory

• Production-Ready Code: Generates well-structured, documented code

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• Groq API key (Get one here)

Installation

1. Clone the repository (or navigate to the project directory):

   cd CodeBuddy

2. Install dependencies:

   # Using uv (recommended)
   uv sync
   
   # Or using pip
   pip install -e .

3. Set up environment variables: Create a .env file in the project root:

   GROQ_API_KEY=your_groq_api_key_here
   LLM_MODEL=openai/gpt-oss-120b  # Optional, defaults to this
   DEBUG=false  # Optional, set to true for verbose logging

Usage

Web Interface (Recommended)

Launch the Streamlit web interface:

streamlit run app.py

Or use the CLI shortcut:

python main.py --web

Then open your browser to http://localhost:8501 and enter your project description.

Command Line Interface

Direct prompt:

python main.py "create a simple calculator website"

Interactive mode:

python main.py --interactive

Help:

python main.py --help

📁 Project Structure

CodeBuddy/
├── agent/
│   ├── __init__.py
│   ├── graph.py          # LangGraph workflow definition
│   ├── prompts.py        # Prompt templates for agents
│   ├── states.py         # Pydantic data models
│   ├── tools.py          # File system tools
│   └── generated_project/ # Generated projects are stored here
├── app.py                # Streamlit web interface
├── main.py               # CLI entry point
├── pyproject.toml        # Project configuration
└── README.md            # This file

🏗️ Architecture

Workflow

1. User Input: User provides a natural language description of the project
2. Planner Agent:
   • Analyzes the request
   • Creates a structured Plan with:
     • Project name and description
     • Technology stack
     • List of features
     • Files to be created
3. Architect Agent:
   • Takes the plan
   • Creates a TaskPlan with ordered ImplementationTask objects
   • Ensures dependencies are handled correctly
4. Coder Agent:
   • Processes each task sequentially
   • Uses tools to read/write files
   • Implements the complete solution

Key Components

agent/graph.py

Defines the LangGraph workflow with three agent nodes:

• planner_agent: Converts user prompt to Plan
• architect_agent: Converts Plan to TaskPlan
• coder_agent: Implements tasks using tools

agent/prompts.py

Contains prompt templates that guide each agent's behavior:

• planner_prompt(): Instructions for the Planner
• architect_prompt(): Instructions for the Architect
• coder_system_prompt(): Instructions for the Coder

agent/states.py

Pydantic models for type safety:

• Plan: High-level project structure
• TaskPlan: Ordered implementation tasks
• ImplementationTask: Individual task definition
• CoderState: Execution state tracking

agent/tools.py

Safe file system operations:

• write_file(): Write content to files
• read_file(): Read file contents
• list_files(): List files in directory
• get_current_directory(): Get project root
• run_cmd(): Execute shell commands (with restrictions)

🛠️ Configuration

Environment Variables

Variable	Description	Default	Required
GROQ_API_KEY	Your Groq API key	-	Yes
LLM_MODEL	LLM model to use	openai/gpt-oss-120b	No
DEBUG	Enable debug logging	false	No

Model Selection

You can use different Groq models by setting LLM_MODEL in your .env file:

• openai/gpt-oss-120b (default)
• llama-3.1-70b-versatile
• mixtral-8x7b-32768
• And other Groq-supported models

📝 Examples

Example 1: Simple Calculator

python main.py "create a simple calculator website with HTML, CSS, and JavaScript"

Example 2: Flask Todo App

python main.py "build a Python Flask web app with a todo list feature and SQLite database"

Example 3: React Component

python main.py "make a React component for a weather dashboard that fetches data from an API"

🔒 Security

• All file operations are restricted to agent/generated_project/
• Path validation prevents directory traversal attacks
• Commands executed via run_cmd are limited to the project directory
• No arbitrary code execution outside the project boundary

🧪 Development

Code Style

The project follows PEP 8 conventions. Optional development tools:

# Install dev dependencies
uv sync --extra dev

# Format code
black .

# Lint code
ruff check .

Running Tests

# Add tests and run them
pytest

📚 API Reference

run_agent(user_prompt: str) -> Dict[str, Any]

Execute the full agent workflow.

Parameters:

• user_prompt: Natural language description of the project

Returns:

• Dictionary containing:
  • plan: The generated Plan object
  • task_plan: The TaskPlan with implementation steps
  • coder_state: Final state of the Coder agent
  • status: Completion status

Raises:

• ValueError: If workflow execution fails

Example

from agent.graph import run_agent

result = run_agent("create a blog website")
plan = result["plan"]
print(f"Project: {plan.name}")

🐛 Troubleshooting

"GROQ_API_KEY not found"

• Ensure you've created a .env file in the project root
• Verify the API key is correctly formatted: GROQ_API_KEY=your_key_here
• Check that python-dotenv is installed

"Path outside project root" error

• This is a security feature. All files must be within agent/generated_project/
• Check that your file paths are relative and don't use .. to go up directories

Agent execution fails

• Check your internet connection (API calls required)
• Verify your Groq API key is valid and has sufficient quota
• Enable DEBUG=true in .env for more detailed error messages

📄 License

This project is open source. Please check the license file for details.

🙏 Acknowledgments

• Built with LangChain and LangGraph
• Powered by Groq for fast LLM inference
• UI built with Streamlit

📧 Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing documentation
• Review the code comments for implementation details

---

Happy Coding! 🚀