🐶 Code Puppy 🐶

"Who needs an IDE?" - someone, probably.

Overview

This project was coded angrily in reaction to Windsurf and Cursor removing access to models and raising prices.

You could also run 50 code puppies at once if you were insane enough.

Would you rather plow a field with one ox or 1024 puppies? - If you pick the ox, better slam that back button in your browser.

Code Puppy is an AI-powered code generation agent, designed to understand programming tasks, generate high-quality code, and explain its reasoning similar to tools like Windsurf and Cursor.

Quick start

uvx code-puppy -i

Features

• Multi-language support: Capable of generating code in various programming languages.
• Interactive CLI: A command-line interface for interactive use.
• Detailed explanations: Provides insights into generated code to understand its logic and structure.

Command Line Animation

Installation

pip install code-puppy

Usage

export MODEL_NAME=gpt-5 # or gemini-2.5-flash-preview-05-20 as an example for Google Gemini models
export OPENAI_API_KEY=<your_openai_api_key> # or GEMINI_API_KEY for Google Gemini models
export CEREBRAS_API_KEY=<your_cerebras_api_key> # for Cerebras models
export YOLO_MODE=true # to bypass the safety confirmation prompt when running shell commands

# or ...

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_ENDPOINT=...

code-puppy --interactive

Running in a super weird corporate environment?

Try this:

export MODEL_NAME=my-custom-model
export YOLO_MODE=true
export MODELS_JSON_PATH=/path/to/custom/models.json

{
    "my-custom-model": {
        "type": "custom_openai",
        "name": "o4-mini-high",
        "max_requests_per_minute": 100,
        "max_retries": 3,
        "retry_base_delay": 10,
        "custom_endpoint": {
            "url": "https://my.custom.endpoint:8080",
            "headers": {
                "X-Api-Key": "<Your_API_Key>",
                "Some-Other-Header": "<Some_Value>"
            },
            "ca_certs_path": "/path/to/cert.pem"
        }
    }
}

Note that the OPENAI_API_KEY or CEREBRAS_API_KEY env variable must be set when using custom_openai endpoints.

Open an issue if your environment is somehow weirder than mine.

Run specific tasks or engage in interactive mode:

# Execute a task directly
code-puppy "write me a C++ hello world program in /tmp/main.cpp then compile it and run it"

Requirements

• Python 3.9+
• OpenAI API key (for GPT models)
• Gemini API key (for Google's Gemini models)
• Cerebras API key (for Cerebras models)
• Anthropic key (for Claude models)
• Ollama endpoint available

License

This project is licensed under the MIT License - see the LICENSE file for details.

Agent Rules

We support AGENT.md files for defining coding standards and styles that your code should comply with. These rules can cover various aspects such as formatting, naming conventions, and even design guidelines.

For examples and more information about agent rules, visit https://agent.md

Using MCP Servers for External Tools

Code Puppy supports MCP (Model Context Protocol) servers to give you access to external code tools and advanced features like code search, documentation lookups, and more—including Context7 (https://context7.com/) integration for deep docs and search!

What is an MCP Server?

An MCP server is a standalone process (can be local or remote) that offers specialized functionality (plugins, doc search, code analysis, etc.). Code Puppy can connect to one or more MCP servers at startup, unlocking these extra commands inside your coding agent.

Configuration

Create a config file at ~/.code_puppy/mcp_servers.json. Here’s an example that connects to a local Context7 MCP server:

{
  "mcp_servers": {
     "context7": { 
        "url": "https://mcp.context7.com/sse"
     }
  }
}

You can list multiple objects (one per server).

How to Use

• Drop the config file in ~/.code_puppy/mcp_servers.json.
• Start your MCP (like context7, or anything compatible).
• Run Code Puppy as usual. It’ll discover and use all configured MCP servers.

Example usage

code-puppy --interactive
# Then ask: Use context7 to look up FastAPI docs!

That’s it! If you need to run more exotic setups or connect to remote MCPs, just update your mcp_servers.json accordingly.

NOTE: Want to add your own server or tool? Just follow the config pattern above—no code changes needed!

---

Conclusion

By using Code Puppy, you can maintain code quality and adhere to design guidelines with ease.