code-puppy


Namecode-puppy JSON
Version 0.0.223 PyPI version JSON
download
home_pageNone
SummaryCode generation agent
upload_time2025-10-24 21:31:59
maintainerNone
docs_urlNone
authorMichael Pfaffenberger
requires_python<3.14,>=3.11
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # 🐶 Code Puppy 🐶
![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)
  <a href="https://github.com/mpfaffenberger/code_puppy"><img src="https://img.shields.io/pypi/pyversions/pydantic-ai.svg" alt="versions"></a>
  <a href="https://github.com/mpfaffenberger/code_puppy/blob/main/LICENSE"><img src="https://img.shields.io/github/license/pydantic/pydantic-ai.svg?v" alt="license"></a>

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

```bash
uvx code-puppy -i
```


## Features

### Session Autosave & Contexts
- Autosaves live in `~/.code_puppy/autosaves` and include a `.pkl` and `_meta.json` per session.
- On startup, you’ll be prompted to optionally load a recent autosave (with message counts and timestamps).
- Autosaves use a stable session ID per interactive run so subsequent prompts overwrite the same session (not N new files). Rotate via `/session new` when you want a fresh session.
- Loading an autosave makes it the active autosave target (future autosaves overwrite that loaded session).
- Loading a manual context with `/load_context <name>` automatically rotates the autosave ID to avoid overwriting anything.
- Helpers:
  - `/session id` shows the current autosave ID and file prefix
  - `/session new` rotates the autosave ID


- **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

![Code Puppy](code_puppy.gif)

## Installation

### UV (Recommended)

```bash
# Install UV if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set UV to always use managed Python (one-time setup)
echo 'export UV_MANAGED_PYTHON=1' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or ~/.bashrc

# Install and run code-puppy
uvx code-puppy -i
```

UV will automatically download the latest compatible Python version (3.11+) if your system doesn't have one.

### pip (Alternative)

```bash
pip install code-puppy
```

*Note: pip installation requires your system Python to be 3.11 or newer.*

### Permanent Python Management

To make UV always use managed Python versions (recommended):

```bash
# Set environment variable permanently
echo 'export UV_MANAGED_PYTHON=1' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # or ~/.bashrc

# Now all UV commands will prefer managed Python installations
uvx code-puppy  # No need for --managed-python flag anymore
```

### Verifying Python Version

```bash
# Check which Python UV will use
uv python find

# Or check the current project's Python
uv run python --version
```

## Usage
```bash
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 SYN_API_KEY=<your https://dev.synthetic.new api key> # for Synthetic provider
# or ...

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

code-puppy --interactive
```

### Synthetic Provider

Code Puppy supports the **Synthetic provider**, which gives you access to various open-source models through a custom OpenAI-compatible endpoint. Set `SYN_API_KEY` to use models like:

- `synthetic-DeepSeek-V3.1-Terminus` (128K context)
- `synthetic-Kimi-K2-Instruct-0905` (256K context)
- `synthetic-Qwen3-Coder-480B-A35B-Instruct` (256K context)
- `synthetic-GLM-4.6` (200K context)

These models are available via `https://api.synthetic.new/openai/v1/` and provide high-quality coding assistance with generous context windows.

Run specific tasks or engage in interactive mode:

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

### Durable Execution

Code Puppy now supports **[DBOS](https://github.com/dbos-inc/dbos-transact-py)** durable execution.

When enabled, every agent is automatically wrapped as a `DBOSAgent`, checkpointing key interactions (including agent inputs, LLM responses, MCP calls, and tool calls) in a database for durability and recovery.

You can toggle DBOS via either of these options:

- CLI config (persists): `/set enable_dbos true` (or `false` to disable)


Config takes precedence if set; otherwise the environment variable is used.

### Configuration

The following environment variables control DBOS behavior:
- `DBOS_CONDUCTOR_KEY`: If set, Code Puppy connects to the [DBOS Management Console](https://console.dbos.dev/). Make sure you first register an app named `dbos-code-puppy` on the console to generate a Conductor key. Default: `None`.
- `DBOS_LOG_LEVEL`: Logging verbosity: `ERROR`, `WARNING`, `INFO`, or `DEBUG`. Default: `ERROR`.
- `DBOS_SYSTEM_DATABASE_URL`: Database URL used by DBOS. Can point to a local SQLite file or a Postgres instance. Example: `postgresql://postgres:dbos@localhost:5432/postgres`. Default: `dbos_store.sqlite` file in the config directory.


## Requirements

- Python 3.11+
- 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](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](https://agent.md)

## Using MCP Servers for External Tools

Use the `/mcp` command to manage MCP (list, start, stop, status, etc.)

In the TUI you can click on MCP settings on the footer and interact with a mini-marketplace.

Watch this video for examples! https://www.youtube.com/watch?v=1t1zEetOqlo


## Round Robin Model Distribution

Code Puppy supports **Round Robin model distribution** to help you overcome rate limits and distribute load across multiple AI models. This feature automatically cycles through configured models with each request, maximizing your API usage while staying within rate limits.

### Configuration
Add a round-robin model configuration to your `~/.code_puppy/extra_models.json` file:

```bash
export CEREBRAS_API_KEY1=csk-...
export CEREBRAS_API_KEY2=csk-...
export CEREBRAS_API_KEY3=csk-...

```

```json
{
  "qwen1": {
    "type": "cerebras",
    "name": "qwen-3-coder-480b",
    "custom_endpoint": {
      "url": "https://api.cerebras.ai/v1",
      "api_key": "$CEREBRAS_API_KEY1"
    },
    "context_length": 131072
  },
  "qwen2": {
    "type": "cerebras",
    "name": "qwen-3-coder-480b",
    "custom_endpoint": {
      "url": "https://api.cerebras.ai/v1",
      "api_key": "$CEREBRAS_API_KEY2"
    },
    "context_length": 131072
  },
  "qwen3": {
    "type": "cerebras",
    "name": "qwen-3-coder-480b",
    "custom_endpoint": {
      "url": "https://api.cerebras.ai/v1",
      "api_key": "$CEREBRAS_API_KEY3"
    },
    "context_length": 131072
  },
  "cerebras_round_robin": {
    "type": "round_robin",
    "models": ["qwen1", "qwen2", "qwen3"],
    "rotate_every": 5
  }
}
```

Then just use /model and tab to select your round-robin model!

The `rotate_every` parameter controls how many requests are made to each model before rotating to the next one. In this example, the round-robin model will use each Qwen model for 5 consecutive requests before moving to the next model in the sequence.

---

## Create your own Agent!!!

Code Puppy features a flexible agent system that allows you to work with specialized AI assistants tailored for different coding tasks. The system supports both built-in Python agents and custom JSON agents that you can create yourself.

## Quick Start

### Check Current Agent
```bash
/agent
```
Shows current active agent and all available agents

### Switch Agent
```bash
/agent <agent-name>
```
Switches to the specified agent

### Create New Agent
```bash
/agent agent-creator
```
Switches to the Agent Creator for building custom agents

### Truncate Message History
```bash
/truncate <N>
```
Truncates the message history to keep only the N most recent messages while protecting the first (system) message. For example:
```bash
/truncate 20
```
Would keep the system message plus the 19 most recent messages, removing older ones from the history.

This is useful for managing context length when you have a long conversation history but only need the most recent interactions.

## Available Agents

### Code-Puppy 🐶 (Default)
- **Name**: `code-puppy`
- **Specialty**: General-purpose coding assistant
- **Personality**: Playful, sarcastic, pedantic about code quality
- **Tools**: Full access to all tools
- **Best for**: All coding tasks, file management, execution
- **Principles**: Clean, concise code following YAGNI, SRP, DRY principles
- **File limit**: Max 600 lines per file (enforced!)

### Agent Creator 🏗️
- **Name**: `agent-creator`
- **Specialty**: Creating custom JSON agent configurations
- **Tools**: File operations, reasoning
- **Best for**: Building new specialized agents
- **Features**: Schema validation, guided creation process

## Agent Types

### Python Agents
Built-in agents implemented in Python with full system integration:
- Discovered automatically from `code_puppy/agents/` directory
- Inherit from `BaseAgent` class
- Full access to system internals
- Examples: `code-puppy`, `agent-creator`

### JSON Agents
User-created agents defined in JSON files:
- Stored in user's agents directory
- Easy to create, share, and modify
- Schema-validated configuration
- Custom system prompts and tool access

## Creating Custom JSON Agents

### Using Agent Creator (Recommended)

1. **Switch to Agent Creator**:
   ```bash
   /agent agent-creator
   ```

2. **Request agent creation**:
   ```
   I want to create a Python tutor agent
   ```

3. **Follow guided process** to define:
   - Name and description
   - Available tools
   - System prompt and behavior
   - Custom settings

4. **Test your new agent**:
   ```bash
   /agent your-new-agent-name
   ```

### Manual JSON Creation

Create JSON files in your agents directory following this schema:

```json
{
  "name": "agent-name",              // REQUIRED: Unique identifier (kebab-case)
  "display_name": "Agent Name 🤖",   // OPTIONAL: Pretty name with emoji
  "description": "What this agent does", // REQUIRED: Clear description
  "system_prompt": "Instructions...",    // REQUIRED: Agent instructions
  "tools": ["tool1", "tool2"],        // REQUIRED: Array of tool names
  "user_prompt": "How can I help?",     // OPTIONAL: Custom greeting
  "tools_config": {                    // OPTIONAL: Tool configuration
    "timeout": 60
  }
}
```

#### Required Fields
- **`name`**: Unique identifier (kebab-case, no spaces)
- **`description`**: What the agent does
- **`system_prompt`**: Agent instructions (string or array)
- **`tools`**: Array of available tool names

#### Optional Fields
- **`display_name`**: Pretty display name (defaults to title-cased name + 🤖)
- **`user_prompt`**: Custom user greeting
- **`tools_config`**: Tool configuration object

## Available Tools

Agents can access these tools based on their configuration:

- **`list_files`**: Directory and file listing
- **`read_file`**: File content reading
- **`grep`**: Text search across files
- **`edit_file`**: File editing and creation
- **`delete_file`**: File deletion
- **`agent_run_shell_command`**: Shell command execution
- **`agent_share_your_reasoning`**: Share reasoning with user

### Tool Access Examples
- **Read-only agent**: `["list_files", "read_file", "grep"]`
- **File editor agent**: `["list_files", "read_file", "edit_file"]`
- **Full access agent**: All tools (like Code-Puppy)

## System Prompt Formats

### String Format
```json
{
  "system_prompt": "You are a helpful coding assistant that specializes in Python development."
}
```

### Array Format (Recommended)
```json
{
  "system_prompt": [
    "You are a helpful coding assistant.",
    "You specialize in Python development.",
    "Always provide clear explanations.",
    "Include practical examples in your responses."
  ]
}
```

## Example JSON Agents

### Python Tutor
```json
{
  "name": "python-tutor",
  "display_name": "Python Tutor 🐍",
  "description": "Teaches Python programming concepts with examples",
  "system_prompt": [
    "You are a patient Python programming tutor.",
    "You explain concepts clearly with practical examples.",
    "You help beginners learn Python step by step.",
    "Always encourage learning and provide constructive feedback."
  ],
  "tools": ["read_file", "edit_file", "agent_share_your_reasoning"],
  "user_prompt": "What Python concept would you like to learn today?"
}
```

### Code Reviewer
```json
{
  "name": "code-reviewer",
  "display_name": "Code Reviewer 🔍",
  "description": "Reviews code for best practices, bugs, and improvements",
  "system_prompt": [
    "You are a senior software engineer doing code reviews.",
    "You focus on code quality, security, and maintainability.",
    "You provide constructive feedback with specific suggestions.",
    "You follow language-specific best practices and conventions."
  ],
  "tools": ["list_files", "read_file", "grep", "agent_share_your_reasoning"],
  "user_prompt": "Which code would you like me to review?"
}
```

### DevOps Helper
```json
{
  "name": "devops-helper",
  "display_name": "DevOps Helper ⚙️",
  "description": "Helps with Docker, CI/CD, and deployment tasks",
  "system_prompt": [
    "You are a DevOps engineer specialized in containerization and CI/CD.",
    "You help with Docker, Kubernetes, GitHub Actions, and deployment.",
    "You provide practical, production-ready solutions.",
    "You always consider security and best practices."
  ],
  "tools": [
    "list_files",
    "read_file",
    "edit_file",
    "agent_run_shell_command",
    "agent_share_your_reasoning"
  ],
  "user_prompt": "What DevOps task can I help you with today?"
}
```

## File Locations

### JSON Agents Directory
- **All platforms**: `~/.code_puppy/agents/`

### Python Agents Directory
- **Built-in**: `code_puppy/agents/` (in package)

## Best Practices

### Naming
- Use kebab-case (hyphens, not spaces)
- Be descriptive: "python-tutor" not "tutor"
- Avoid special characters

### System Prompts
- Be specific about the agent's role
- Include personality traits
- Specify output format preferences
- Use array format for multi-line prompts

### Tool Selection
- Only include tools the agent actually needs
- Most agents need `agent_share_your_reasoning`
- File manipulation agents need `read_file`, `edit_file`
- Research agents need `grep`, `list_files`

### Display Names
- Include relevant emoji for personality
- Make it friendly and recognizable
- Keep it concise

## System Architecture

### Agent Discovery
The system automatically discovers agents by:
1. **Python Agents**: Scanning `code_puppy/agents/` for classes inheriting from `BaseAgent`
2. **JSON Agents**: Scanning user's agents directory for `*-agent.json` files
3. Instantiating and registering discovered agents

### JSONAgent Implementation
JSON agents are powered by the `JSONAgent` class (`code_puppy/agents/json_agent.py`):
- Inherits from `BaseAgent` for full system integration
- Loads configuration from JSON files with robust validation
- Supports all BaseAgent features (tools, prompts, settings)
- Cross-platform user directory support
- Built-in error handling and schema validation

### BaseAgent Interface
Both Python and JSON agents implement this interface:
- `name`: Unique identifier
- `display_name`: Human-readable name with emoji
- `description`: Brief description of purpose
- `get_system_prompt()`: Returns agent-specific system prompt
- `get_available_tools()`: Returns list of tool names

### Agent Manager Integration
The `agent_manager.py` provides:
- Unified registry for both Python and JSON agents
- Seamless switching between agent types
- Configuration persistence across sessions
- Automatic caching for performance

### System Integration
- **Command Interface**: `/agent` command works with all agent types
- **Tool Filtering**: Dynamic tool access control per agent
- **Main Agent System**: Loads and manages both agent types
- **Cross-Platform**: Consistent behavior across all platforms

## Adding Python Agents

To create a new Python agent:

1. Create file in `code_puppy/agents/` (e.g., `my_agent.py`)
2. Implement class inheriting from `BaseAgent`
3. Define required properties and methods
4. Agent will be automatically discovered

Example implementation:

```python
from .base_agent import BaseAgent

class MyCustomAgent(BaseAgent):
    @property
    def name(self) -> str:
        return "my-agent"

    @property
    def display_name(self) -> str:
        return "My Custom Agent ✨"

    @property
    def description(self) -> str:
        return "A custom agent for specialized tasks"

    def get_system_prompt(self) -> str:
        return "Your custom system prompt here..."

    def get_available_tools(self) -> list[str]:
        return [
            "list_files",
            "read_file",
            "grep",
            "edit_file",
            "delete_file",
            "agent_run_shell_command",
            "agent_share_your_reasoning"
        ]
```

## Troubleshooting

### Agent Not Found
- Ensure JSON file is in correct directory
- Check JSON syntax is valid
- Restart Code Puppy or clear agent cache
- Verify filename ends with `-agent.json`

### Validation Errors
- Use Agent Creator for guided validation
- Check all required fields are present
- Verify tool names are correct
- Ensure name uses kebab-case

### Permission Issues
- Make sure agents directory is writable
- Check file permissions on JSON files
- Verify directory path exists

## Advanced Features

### Tool Configuration
```json
{
  "tools_config": {
    "timeout": 120,
    "max_retries": 3
  }
}
```

### Multi-line System Prompts
```json
{
  "system_prompt": [
    "Line 1 of instructions",
    "Line 2 of instructions",
    "Line 3 of instructions"
  ]
}
```

## Future Extensibility

The agent system supports future expansion:

- **Specialized Agents**: Code reviewers, debuggers, architects
- **Domain-Specific Agents**: Web dev, data science, DevOps, mobile
- **Personality Variations**: Different communication styles
- **Context-Aware Agents**: Adapt based on project type
- **Team Agents**: Shared configurations for coding standards
- **Plugin System**: Community-contributed agents

## Benefits of JSON Agents

1. **Easy Customization**: Create agents without Python knowledge
2. **Team Sharing**: JSON agents can be shared across teams
3. **Rapid Prototyping**: Quick agent creation for specific workflows
4. **Version Control**: JSON agents are git-friendly
5. **Built-in Validation**: Schema validation with helpful error messages
6. **Cross-Platform**: Works consistently across all platforms
7. **Backward Compatible**: Doesn't affect existing Python agents

## Implementation Details

### Files in System
- **Core Implementation**: `code_puppy/agents/json_agent.py`
- **Agent Discovery**: Integrated in `code_puppy/agents/agent_manager.py`
- **Command Interface**: Works through existing `/agent` command
- **Testing**: Comprehensive test suite in `tests/test_json_agents.py`

### JSON Agent Loading Process
1. System scans `~/.code_puppy/agents/` for `*-agent.json` files
2. `JSONAgent` class loads and validates each JSON configuration
3. Agents are registered in unified agent registry
4. Users can switch to JSON agents via `/agent <name>` command
5. Tool access and system prompts work identically to Python agents

### Error Handling
- Invalid JSON syntax: Clear error messages with line numbers
- Missing required fields: Specific field validation errors
- Invalid tool names: Warning with list of available tools
- File permission issues: Helpful troubleshooting guidance

## Future Possibilities

- **Agent Templates**: Pre-built JSON agents for common tasks
- **Visual Editor**: GUI for creating JSON agents
- **Hot Reloading**: Update agents without restart
- **Agent Marketplace**: Share and discover community agents
- **Enhanced Validation**: More sophisticated schema validation
- **Team Agents**: Shared configurations for coding standards

## Contributing

### Sharing JSON Agents
1. Create and test your agent thoroughly
2. Ensure it follows best practices
3. Submit a pull request with agent JSON
4. Include documentation and examples
5. Test across different platforms

### Python Agent Contributions
1. Follow existing code style
2. Include comprehensive tests
3. Document the agent's purpose and usage
4. Submit pull request for review
5. Ensure backward compatibility

### Agent Templates
Consider contributing agent templates for:
- Code reviewers and auditors
- Language-specific tutors
- DevOps and deployment helpers
- Documentation writers
- Testing specialists

---

**Happy Agent Building!** 🚀 Code Puppy now supports both Python and JSON agents, making it easy for anyone to create custom AI coding assistants! 🐶✨


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

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "code-puppy",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<3.14,>=3.11",
    "maintainer_email": null,
    "keywords": null,
    "author": "Michael Pfaffenberger",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/40/57/3e7f1017067d314eaa3c64a2954f0f617b6ea0df9e0991d768555f2e8f58/code_puppy-0.0.223.tar.gz",
    "platform": null,
    "description": "# \ud83d\udc36 Code Puppy \ud83d\udc36\n![Build Status](https://img.shields.io/badge/build-passing-brightgreen)\n![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)\n  <a href=\"https://github.com/mpfaffenberger/code_puppy\"><img src=\"https://img.shields.io/pypi/pyversions/pydantic-ai.svg\" alt=\"versions\"></a>\n  <a href=\"https://github.com/mpfaffenberger/code_puppy/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/pydantic/pydantic-ai.svg?v\" alt=\"license\"></a>\n\n*\"Who needs an IDE?\"* - someone, probably.\n\n## Overview\n\n*This project was coded angrily in reaction to Windsurf and Cursor removing access to models and raising prices.*\n\n*You could also run 50 code puppies at once if you were insane enough.*\n\n*Would you rather plow a field with one ox or 1024 puppies?*\n    - If you pick the ox, better slam that back button in your browser.\n\n\nCode 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.\n\n## Quick start\n\n```bash\nuvx code-puppy -i\n```\n\n\n## Features\n\n### Session Autosave & Contexts\n- Autosaves live in `~/.code_puppy/autosaves` and include a `.pkl` and `_meta.json` per session.\n- On startup, you\u2019ll be prompted to optionally load a recent autosave (with message counts and timestamps).\n- Autosaves use a stable session ID per interactive run so subsequent prompts overwrite the same session (not N new files). Rotate via `/session new` when you want a fresh session.\n- Loading an autosave makes it the active autosave target (future autosaves overwrite that loaded session).\n- Loading a manual context with `/load_context <name>` automatically rotates the autosave ID to avoid overwriting anything.\n- Helpers:\n  - `/session id` shows the current autosave ID and file prefix\n  - `/session new` rotates the autosave ID\n\n\n- **Multi-language support**: Capable of generating code in various programming languages.\n- **Interactive CLI**: A command-line interface for interactive use.\n- **Detailed explanations**: Provides insights into generated code to understand its logic and structure.\n\n## Command Line Animation\n\n![Code Puppy](code_puppy.gif)\n\n## Installation\n\n### UV (Recommended)\n\n```bash\n# Install UV if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Set UV to always use managed Python (one-time setup)\necho 'export UV_MANAGED_PYTHON=1' >> ~/.zshrc  # or ~/.bashrc\nsource ~/.zshrc  # or ~/.bashrc\n\n# Install and run code-puppy\nuvx code-puppy -i\n```\n\nUV will automatically download the latest compatible Python version (3.11+) if your system doesn't have one.\n\n### pip (Alternative)\n\n```bash\npip install code-puppy\n```\n\n*Note: pip installation requires your system Python to be 3.11 or newer.*\n\n### Permanent Python Management\n\nTo make UV always use managed Python versions (recommended):\n\n```bash\n# Set environment variable permanently\necho 'export UV_MANAGED_PYTHON=1' >> ~/.zshrc  # or ~/.bashrc\nsource ~/.zshrc  # or ~/.bashrc\n\n# Now all UV commands will prefer managed Python installations\nuvx code-puppy  # No need for --managed-python flag anymore\n```\n\n### Verifying Python Version\n\n```bash\n# Check which Python UV will use\nuv python find\n\n# Or check the current project's Python\nuv run python --version\n```\n\n## Usage\n```bash\nexport MODEL_NAME=gpt-5 # or gemini-2.5-flash-preview-05-20 as an example for Google Gemini models\nexport OPENAI_API_KEY=<your_openai_api_key> # or GEMINI_API_KEY for Google Gemini models\nexport CEREBRAS_API_KEY=<your_cerebras_api_key> # for Cerebras models\nexport SYN_API_KEY=<your https://dev.synthetic.new api key> # for Synthetic provider\n# or ...\n\nexport AZURE_OPENAI_API_KEY=...\nexport AZURE_OPENAI_ENDPOINT=...\n\ncode-puppy --interactive\n```\n\n### Synthetic Provider\n\nCode Puppy supports the **Synthetic provider**, which gives you access to various open-source models through a custom OpenAI-compatible endpoint. Set `SYN_API_KEY` to use models like:\n\n- `synthetic-DeepSeek-V3.1-Terminus` (128K context)\n- `synthetic-Kimi-K2-Instruct-0905` (256K context)\n- `synthetic-Qwen3-Coder-480B-A35B-Instruct` (256K context)\n- `synthetic-GLM-4.6` (200K context)\n\nThese models are available via `https://api.synthetic.new/openai/v1/` and provide high-quality coding assistance with generous context windows.\n\nRun specific tasks or engage in interactive mode:\n\n```bash\n# Execute a task directly\ncode-puppy \"write me a C++ hello world program in /tmp/main.cpp then compile it and run it\"\n```\n\n### Durable Execution\n\nCode Puppy now supports **[DBOS](https://github.com/dbos-inc/dbos-transact-py)** durable execution.\n\nWhen enabled, every agent is automatically wrapped as a `DBOSAgent`, checkpointing key interactions (including agent inputs, LLM responses, MCP calls, and tool calls) in a database for durability and recovery.\n\nYou can toggle DBOS via either of these options:\n\n- CLI config (persists): `/set enable_dbos true` (or `false` to disable)\n\n\nConfig takes precedence if set; otherwise the environment variable is used.\n\n### Configuration\n\nThe following environment variables control DBOS behavior:\n- `DBOS_CONDUCTOR_KEY`: If set, Code Puppy connects to the [DBOS Management Console](https://console.dbos.dev/). Make sure you first register an app named `dbos-code-puppy` on the console to generate a Conductor key. Default: `None`.\n- `DBOS_LOG_LEVEL`: Logging verbosity: `ERROR`, `WARNING`, `INFO`, or `DEBUG`. Default: `ERROR`.\n- `DBOS_SYSTEM_DATABASE_URL`: Database URL used by DBOS. Can point to a local SQLite file or a Postgres instance. Example: `postgresql://postgres:dbos@localhost:5432/postgres`. Default: `dbos_store.sqlite` file in the config directory.\n\n\n## Requirements\n\n- Python 3.11+\n- OpenAI API key (for GPT models)\n- Gemini API key (for Google's Gemini models)\n- Cerebras API key (for Cerebras models)\n- Anthropic key (for Claude models)\n- Ollama endpoint available\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Agent Rules\nWe 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.\n\nFor examples and more information about agent rules, visit [https://agent.md](https://agent.md)\n\n## Using MCP Servers for External Tools\n\nUse the `/mcp` command to manage MCP (list, start, stop, status, etc.)\n\nIn the TUI you can click on MCP settings on the footer and interact with a mini-marketplace.\n\nWatch this video for examples! https://www.youtube.com/watch?v=1t1zEetOqlo\n\n\n## Round Robin Model Distribution\n\nCode Puppy supports **Round Robin model distribution** to help you overcome rate limits and distribute load across multiple AI models. This feature automatically cycles through configured models with each request, maximizing your API usage while staying within rate limits.\n\n### Configuration\nAdd a round-robin model configuration to your `~/.code_puppy/extra_models.json` file:\n\n```bash\nexport CEREBRAS_API_KEY1=csk-...\nexport CEREBRAS_API_KEY2=csk-...\nexport CEREBRAS_API_KEY3=csk-...\n\n```\n\n```json\n{\n  \"qwen1\": {\n    \"type\": \"cerebras\",\n    \"name\": \"qwen-3-coder-480b\",\n    \"custom_endpoint\": {\n      \"url\": \"https://api.cerebras.ai/v1\",\n      \"api_key\": \"$CEREBRAS_API_KEY1\"\n    },\n    \"context_length\": 131072\n  },\n  \"qwen2\": {\n    \"type\": \"cerebras\",\n    \"name\": \"qwen-3-coder-480b\",\n    \"custom_endpoint\": {\n      \"url\": \"https://api.cerebras.ai/v1\",\n      \"api_key\": \"$CEREBRAS_API_KEY2\"\n    },\n    \"context_length\": 131072\n  },\n  \"qwen3\": {\n    \"type\": \"cerebras\",\n    \"name\": \"qwen-3-coder-480b\",\n    \"custom_endpoint\": {\n      \"url\": \"https://api.cerebras.ai/v1\",\n      \"api_key\": \"$CEREBRAS_API_KEY3\"\n    },\n    \"context_length\": 131072\n  },\n  \"cerebras_round_robin\": {\n    \"type\": \"round_robin\",\n    \"models\": [\"qwen1\", \"qwen2\", \"qwen3\"],\n    \"rotate_every\": 5\n  }\n}\n```\n\nThen just use /model and tab to select your round-robin model!\n\nThe `rotate_every` parameter controls how many requests are made to each model before rotating to the next one. In this example, the round-robin model will use each Qwen model for 5 consecutive requests before moving to the next model in the sequence.\n\n---\n\n## Create your own Agent!!!\n\nCode Puppy features a flexible agent system that allows you to work with specialized AI assistants tailored for different coding tasks. The system supports both built-in Python agents and custom JSON agents that you can create yourself.\n\n## Quick Start\n\n### Check Current Agent\n```bash\n/agent\n```\nShows current active agent and all available agents\n\n### Switch Agent\n```bash\n/agent <agent-name>\n```\nSwitches to the specified agent\n\n### Create New Agent\n```bash\n/agent agent-creator\n```\nSwitches to the Agent Creator for building custom agents\n\n### Truncate Message History\n```bash\n/truncate <N>\n```\nTruncates the message history to keep only the N most recent messages while protecting the first (system) message. For example:\n```bash\n/truncate 20\n```\nWould keep the system message plus the 19 most recent messages, removing older ones from the history.\n\nThis is useful for managing context length when you have a long conversation history but only need the most recent interactions.\n\n## Available Agents\n\n### Code-Puppy \ud83d\udc36 (Default)\n- **Name**: `code-puppy`\n- **Specialty**: General-purpose coding assistant\n- **Personality**: Playful, sarcastic, pedantic about code quality\n- **Tools**: Full access to all tools\n- **Best for**: All coding tasks, file management, execution\n- **Principles**: Clean, concise code following YAGNI, SRP, DRY principles\n- **File limit**: Max 600 lines per file (enforced!)\n\n### Agent Creator \ud83c\udfd7\ufe0f\n- **Name**: `agent-creator`\n- **Specialty**: Creating custom JSON agent configurations\n- **Tools**: File operations, reasoning\n- **Best for**: Building new specialized agents\n- **Features**: Schema validation, guided creation process\n\n## Agent Types\n\n### Python Agents\nBuilt-in agents implemented in Python with full system integration:\n- Discovered automatically from `code_puppy/agents/` directory\n- Inherit from `BaseAgent` class\n- Full access to system internals\n- Examples: `code-puppy`, `agent-creator`\n\n### JSON Agents\nUser-created agents defined in JSON files:\n- Stored in user's agents directory\n- Easy to create, share, and modify\n- Schema-validated configuration\n- Custom system prompts and tool access\n\n## Creating Custom JSON Agents\n\n### Using Agent Creator (Recommended)\n\n1. **Switch to Agent Creator**:\n   ```bash\n   /agent agent-creator\n   ```\n\n2. **Request agent creation**:\n   ```\n   I want to create a Python tutor agent\n   ```\n\n3. **Follow guided process** to define:\n   - Name and description\n   - Available tools\n   - System prompt and behavior\n   - Custom settings\n\n4. **Test your new agent**:\n   ```bash\n   /agent your-new-agent-name\n   ```\n\n### Manual JSON Creation\n\nCreate JSON files in your agents directory following this schema:\n\n```json\n{\n  \"name\": \"agent-name\",              // REQUIRED: Unique identifier (kebab-case)\n  \"display_name\": \"Agent Name \ud83e\udd16\",   // OPTIONAL: Pretty name with emoji\n  \"description\": \"What this agent does\", // REQUIRED: Clear description\n  \"system_prompt\": \"Instructions...\",    // REQUIRED: Agent instructions\n  \"tools\": [\"tool1\", \"tool2\"],        // REQUIRED: Array of tool names\n  \"user_prompt\": \"How can I help?\",     // OPTIONAL: Custom greeting\n  \"tools_config\": {                    // OPTIONAL: Tool configuration\n    \"timeout\": 60\n  }\n}\n```\n\n#### Required Fields\n- **`name`**: Unique identifier (kebab-case, no spaces)\n- **`description`**: What the agent does\n- **`system_prompt`**: Agent instructions (string or array)\n- **`tools`**: Array of available tool names\n\n#### Optional Fields\n- **`display_name`**: Pretty display name (defaults to title-cased name + \ud83e\udd16)\n- **`user_prompt`**: Custom user greeting\n- **`tools_config`**: Tool configuration object\n\n## Available Tools\n\nAgents can access these tools based on their configuration:\n\n- **`list_files`**: Directory and file listing\n- **`read_file`**: File content reading\n- **`grep`**: Text search across files\n- **`edit_file`**: File editing and creation\n- **`delete_file`**: File deletion\n- **`agent_run_shell_command`**: Shell command execution\n- **`agent_share_your_reasoning`**: Share reasoning with user\n\n### Tool Access Examples\n- **Read-only agent**: `[\"list_files\", \"read_file\", \"grep\"]`\n- **File editor agent**: `[\"list_files\", \"read_file\", \"edit_file\"]`\n- **Full access agent**: All tools (like Code-Puppy)\n\n## System Prompt Formats\n\n### String Format\n```json\n{\n  \"system_prompt\": \"You are a helpful coding assistant that specializes in Python development.\"\n}\n```\n\n### Array Format (Recommended)\n```json\n{\n  \"system_prompt\": [\n    \"You are a helpful coding assistant.\",\n    \"You specialize in Python development.\",\n    \"Always provide clear explanations.\",\n    \"Include practical examples in your responses.\"\n  ]\n}\n```\n\n## Example JSON Agents\n\n### Python Tutor\n```json\n{\n  \"name\": \"python-tutor\",\n  \"display_name\": \"Python Tutor \ud83d\udc0d\",\n  \"description\": \"Teaches Python programming concepts with examples\",\n  \"system_prompt\": [\n    \"You are a patient Python programming tutor.\",\n    \"You explain concepts clearly with practical examples.\",\n    \"You help beginners learn Python step by step.\",\n    \"Always encourage learning and provide constructive feedback.\"\n  ],\n  \"tools\": [\"read_file\", \"edit_file\", \"agent_share_your_reasoning\"],\n  \"user_prompt\": \"What Python concept would you like to learn today?\"\n}\n```\n\n### Code Reviewer\n```json\n{\n  \"name\": \"code-reviewer\",\n  \"display_name\": \"Code Reviewer \ud83d\udd0d\",\n  \"description\": \"Reviews code for best practices, bugs, and improvements\",\n  \"system_prompt\": [\n    \"You are a senior software engineer doing code reviews.\",\n    \"You focus on code quality, security, and maintainability.\",\n    \"You provide constructive feedback with specific suggestions.\",\n    \"You follow language-specific best practices and conventions.\"\n  ],\n  \"tools\": [\"list_files\", \"read_file\", \"grep\", \"agent_share_your_reasoning\"],\n  \"user_prompt\": \"Which code would you like me to review?\"\n}\n```\n\n### DevOps Helper\n```json\n{\n  \"name\": \"devops-helper\",\n  \"display_name\": \"DevOps Helper \u2699\ufe0f\",\n  \"description\": \"Helps with Docker, CI/CD, and deployment tasks\",\n  \"system_prompt\": [\n    \"You are a DevOps engineer specialized in containerization and CI/CD.\",\n    \"You help with Docker, Kubernetes, GitHub Actions, and deployment.\",\n    \"You provide practical, production-ready solutions.\",\n    \"You always consider security and best practices.\"\n  ],\n  \"tools\": [\n    \"list_files\",\n    \"read_file\",\n    \"edit_file\",\n    \"agent_run_shell_command\",\n    \"agent_share_your_reasoning\"\n  ],\n  \"user_prompt\": \"What DevOps task can I help you with today?\"\n}\n```\n\n## File Locations\n\n### JSON Agents Directory\n- **All platforms**: `~/.code_puppy/agents/`\n\n### Python Agents Directory\n- **Built-in**: `code_puppy/agents/` (in package)\n\n## Best Practices\n\n### Naming\n- Use kebab-case (hyphens, not spaces)\n- Be descriptive: \"python-tutor\" not \"tutor\"\n- Avoid special characters\n\n### System Prompts\n- Be specific about the agent's role\n- Include personality traits\n- Specify output format preferences\n- Use array format for multi-line prompts\n\n### Tool Selection\n- Only include tools the agent actually needs\n- Most agents need `agent_share_your_reasoning`\n- File manipulation agents need `read_file`, `edit_file`\n- Research agents need `grep`, `list_files`\n\n### Display Names\n- Include relevant emoji for personality\n- Make it friendly and recognizable\n- Keep it concise\n\n## System Architecture\n\n### Agent Discovery\nThe system automatically discovers agents by:\n1. **Python Agents**: Scanning `code_puppy/agents/` for classes inheriting from `BaseAgent`\n2. **JSON Agents**: Scanning user's agents directory for `*-agent.json` files\n3. Instantiating and registering discovered agents\n\n### JSONAgent Implementation\nJSON agents are powered by the `JSONAgent` class (`code_puppy/agents/json_agent.py`):\n- Inherits from `BaseAgent` for full system integration\n- Loads configuration from JSON files with robust validation\n- Supports all BaseAgent features (tools, prompts, settings)\n- Cross-platform user directory support\n- Built-in error handling and schema validation\n\n### BaseAgent Interface\nBoth Python and JSON agents implement this interface:\n- `name`: Unique identifier\n- `display_name`: Human-readable name with emoji\n- `description`: Brief description of purpose\n- `get_system_prompt()`: Returns agent-specific system prompt\n- `get_available_tools()`: Returns list of tool names\n\n### Agent Manager Integration\nThe `agent_manager.py` provides:\n- Unified registry for both Python and JSON agents\n- Seamless switching between agent types\n- Configuration persistence across sessions\n- Automatic caching for performance\n\n### System Integration\n- **Command Interface**: `/agent` command works with all agent types\n- **Tool Filtering**: Dynamic tool access control per agent\n- **Main Agent System**: Loads and manages both agent types\n- **Cross-Platform**: Consistent behavior across all platforms\n\n## Adding Python Agents\n\nTo create a new Python agent:\n\n1. Create file in `code_puppy/agents/` (e.g., `my_agent.py`)\n2. Implement class inheriting from `BaseAgent`\n3. Define required properties and methods\n4. Agent will be automatically discovered\n\nExample implementation:\n\n```python\nfrom .base_agent import BaseAgent\n\nclass MyCustomAgent(BaseAgent):\n    @property\n    def name(self) -> str:\n        return \"my-agent\"\n\n    @property\n    def display_name(self) -> str:\n        return \"My Custom Agent \u2728\"\n\n    @property\n    def description(self) -> str:\n        return \"A custom agent for specialized tasks\"\n\n    def get_system_prompt(self) -> str:\n        return \"Your custom system prompt here...\"\n\n    def get_available_tools(self) -> list[str]:\n        return [\n            \"list_files\",\n            \"read_file\",\n            \"grep\",\n            \"edit_file\",\n            \"delete_file\",\n            \"agent_run_shell_command\",\n            \"agent_share_your_reasoning\"\n        ]\n```\n\n## Troubleshooting\n\n### Agent Not Found\n- Ensure JSON file is in correct directory\n- Check JSON syntax is valid\n- Restart Code Puppy or clear agent cache\n- Verify filename ends with `-agent.json`\n\n### Validation Errors\n- Use Agent Creator for guided validation\n- Check all required fields are present\n- Verify tool names are correct\n- Ensure name uses kebab-case\n\n### Permission Issues\n- Make sure agents directory is writable\n- Check file permissions on JSON files\n- Verify directory path exists\n\n## Advanced Features\n\n### Tool Configuration\n```json\n{\n  \"tools_config\": {\n    \"timeout\": 120,\n    \"max_retries\": 3\n  }\n}\n```\n\n### Multi-line System Prompts\n```json\n{\n  \"system_prompt\": [\n    \"Line 1 of instructions\",\n    \"Line 2 of instructions\",\n    \"Line 3 of instructions\"\n  ]\n}\n```\n\n## Future Extensibility\n\nThe agent system supports future expansion:\n\n- **Specialized Agents**: Code reviewers, debuggers, architects\n- **Domain-Specific Agents**: Web dev, data science, DevOps, mobile\n- **Personality Variations**: Different communication styles\n- **Context-Aware Agents**: Adapt based on project type\n- **Team Agents**: Shared configurations for coding standards\n- **Plugin System**: Community-contributed agents\n\n## Benefits of JSON Agents\n\n1. **Easy Customization**: Create agents without Python knowledge\n2. **Team Sharing**: JSON agents can be shared across teams\n3. **Rapid Prototyping**: Quick agent creation for specific workflows\n4. **Version Control**: JSON agents are git-friendly\n5. **Built-in Validation**: Schema validation with helpful error messages\n6. **Cross-Platform**: Works consistently across all platforms\n7. **Backward Compatible**: Doesn't affect existing Python agents\n\n## Implementation Details\n\n### Files in System\n- **Core Implementation**: `code_puppy/agents/json_agent.py`\n- **Agent Discovery**: Integrated in `code_puppy/agents/agent_manager.py`\n- **Command Interface**: Works through existing `/agent` command\n- **Testing**: Comprehensive test suite in `tests/test_json_agents.py`\n\n### JSON Agent Loading Process\n1. System scans `~/.code_puppy/agents/` for `*-agent.json` files\n2. `JSONAgent` class loads and validates each JSON configuration\n3. Agents are registered in unified agent registry\n4. Users can switch to JSON agents via `/agent <name>` command\n5. Tool access and system prompts work identically to Python agents\n\n### Error Handling\n- Invalid JSON syntax: Clear error messages with line numbers\n- Missing required fields: Specific field validation errors\n- Invalid tool names: Warning with list of available tools\n- File permission issues: Helpful troubleshooting guidance\n\n## Future Possibilities\n\n- **Agent Templates**: Pre-built JSON agents for common tasks\n- **Visual Editor**: GUI for creating JSON agents\n- **Hot Reloading**: Update agents without restart\n- **Agent Marketplace**: Share and discover community agents\n- **Enhanced Validation**: More sophisticated schema validation\n- **Team Agents**: Shared configurations for coding standards\n\n## Contributing\n\n### Sharing JSON Agents\n1. Create and test your agent thoroughly\n2. Ensure it follows best practices\n3. Submit a pull request with agent JSON\n4. Include documentation and examples\n5. Test across different platforms\n\n### Python Agent Contributions\n1. Follow existing code style\n2. Include comprehensive tests\n3. Document the agent's purpose and usage\n4. Submit pull request for review\n5. Ensure backward compatibility\n\n### Agent Templates\nConsider contributing agent templates for:\n- Code reviewers and auditors\n- Language-specific tutors\n- DevOps and deployment helpers\n- Documentation writers\n- Testing specialists\n\n---\n\n**Happy Agent Building!** \ud83d\ude80 Code Puppy now supports both Python and JSON agents, making it easy for anyone to create custom AI coding assistants! \ud83d\udc36\u2728\n\n\n## Conclusion\nBy using Code Puppy, you can maintain code quality and adhere to design guidelines with ease.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Code generation agent",
    "version": "0.0.223",
    "project_urls": {
        "HomePage": "https://github.com/mpfaffenberger/code_puppy",
        "repository": "https://github.com/mpfaffenberger/code_puppy"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "7b5ea26b131923031b8ca92794a070f7b3b84cddd32b8a138aec079453e352e3",
                "md5": "5ac51b32068e279e771eab397a4f3089",
                "sha256": "424cb77dd7f7e07c8c9fcea38acf1e15cec9005cffacb40c46d211f3dfa39276"
            },
            "downloads": -1,
            "filename": "code_puppy-0.0.223-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5ac51b32068e279e771eab397a4f3089",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.14,>=3.11",
            "size": 346243,
            "upload_time": "2025-10-24T21:31:57",
            "upload_time_iso_8601": "2025-10-24T21:31:57.370740Z",
            "url": "https://files.pythonhosted.org/packages/7b/5e/a26b131923031b8ca92794a070f7b3b84cddd32b8a138aec079453e352e3/code_puppy-0.0.223-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "40573e7f1017067d314eaa3c64a2954f0f617b6ea0df9e0991d768555f2e8f58",
                "md5": "3a878e3f78f1692fdad643d512916a21",
                "sha256": "8044dc30f1912af4dcbd327b1319fdd5c93b5cf467c6e6d1a981ae92eb1c69b5"
            },
            "downloads": -1,
            "filename": "code_puppy-0.0.223.tar.gz",
            "has_sig": false,
            "md5_digest": "3a878e3f78f1692fdad643d512916a21",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.14,>=3.11",
            "size": 268161,
            "upload_time": "2025-10-24T21:31:59",
            "upload_time_iso_8601": "2025-10-24T21:31:59.088310Z",
            "url": "https://files.pythonhosted.org/packages/40/57/3e7f1017067d314eaa3c64a2954f0f617b6ea0df9e0991d768555f2e8f58/code_puppy-0.0.223.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-24 21:31:59",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "mpfaffenberger",
    "github_project": "code_puppy",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "code-puppy"
}
Michael Pfaffenberger
Elapsed time: 3.82566s