Code Puppy
A sassy, privacy-first terminal AI coding agent that reads and edits your codebase, runs commands, and rotates across multiple models — making expensive IDEs look outdated.
Custom JSON agents support per-agent tool selection with minimal-toolset examples (read-only agent), scoring 2; but the default code-puppy agent has 'Full access to all tools' including shell execution and delete_file — deducted there. User confirmation is entirely absent from the evidence: no approval flow is documented for shell commands or file deletion, scoring 0. Data-flow transparency rests on a '100% privacy' badge anchor with no substance in evidence, scoring 1. Sensitive data handling: API keys referenced via env vars, keyring dependency, /meta-logout credential removal — scoring 2. Dependency security: loose pins and a questionable entry (httpx2 alongside httpx), no lockfile or audit evidence — scoring 1. External effects: shell, file deletion, and browser tools exist with no documented mitigations — scoring 1. Rollback: DBOS durable execution with crash recovery and /dbos toggles, /truncate for history — scoring 2. MIT license and named authorship complete — scoring 2.
Clear self-contradiction: README says durable execution is 'off by default in the dependency tree' then states '/set enable_dbos false to disable (enabled by default)'; CI notes models. ships empty while README implies out-of-box models — scoring 1. Dependency availability is decent: models.dev offline fallback, configurable timeouts, Android build-cache guidance — scoring 2. Failure messages: smart warnings for unsupported providers and no-tool-calling models, structured error messages visible in tests — scoring 2.
Audience/scenario coverage is thorough: multi-provider, multi-agent, Android/Termux, custom commands — scoring 3. Capability boundaries: 39+ providers honestly flagged as untested, Playwright unavailable on Android, known Windows test failures noted in CI comments — scoring 2. Trigger precision: slash commands and AGENTS.md load order well defined — scoring 2. Environment fit: macOS/Linux/Windows/Termux install paths with platform caveats, though Windows support is admitted incomplete — scoring 2.
Information architecture is usable but the README is long with duplicated sections (DBOS described twice, timeouts twice) — scoring 2. Install notes are thorough across uv/pipx/Termux — scoring 3. Naming stability: kebab-case conventions, consistent tool/agent names — scoring 2. Rich examples but no FAQ — scoring 2. Known limitations honestly labeled (untested providers, platform gaps) — scoring 2. LICENSE file, pyproject, and badge all consistently MIT — scoring 3. Version 0.0.827 present but changelog lives only in an external Kittylog link, not in the repo — scoring 1. Maintenance responsibility: named author, CI, Discord exist, but no contribution/governance/security-policy file in evidence — scoring 1.
Output usability: CLI/TUI, rich rendering, /truncate context management — scoring 2. Marginal value: 65+ provider aggregation, JSON agent system, DBOS durability differentiate it — scoring 2. Cost-benefit: multiple provider API keys required; pricing appears only in /add_model previews; no quantified cost guidance — scoring 1.
Claim traceability is weak: 170k downloads and Build/Tests Passing badges point to external status not verifiable in-repo; marketing claims ('1024 puppies') mix with facts — scoring 1. Cross-source corroboration: README, pyproject, and CI largely agree except the DBOS default and models. contradictions — scoring 1. Fact/inference separation is partially achieved ('not been tested thoroughly' labels) but key claims like the privacy commitment lack supporting detail — scoring 1.
- The default agent holds full tool access including shell execution and file deletion, with no user-confirmation mechanism documented — add an approval layer or use restricted-toolset custom agents before production use.
- Documentation is self-contradictory: DBOS durable execution is described as both off-by-default and enabled-by-default; verify actual behavior in the current release.
- 39+ providers' OpenAI-compatible endpoints are explicitly 'not tested thoroughly'; evaluate before sending API keys through them.
- The privacy commitment is a badge-level assertion with no substantive data-flow documentation; Meta OAuth reuses ~/.config/muse/auth. — confirm the implications of shared credentials.
- Changelog, contribution guide, and security policy are absent from the repository; maintenance sustainability cannot be assessed from source.
What does this agent do, and when should you use it?
Code Puppy is a terminal-based AI coding agent built on Pydantic AI, open-sourced under the MIT license by mpfaffenberger on GitHub (mpfaffenberger/code_puppy) and distributed via PyPI as code-puppy with over 170k downloads. Launched with `uvx code-puppy`, it reads and lists files, greps, creates and edits files, applies multi-file patches, runs shell commands, and explains its reasoning. It integrates with 65+ providers and 1000+ models via models.dev (including OpenAI, Anthropic, Google, Cerebras, Groq, xAI, local Ollama models, and Meta Muse OAuth) and offers round-robin distribution to work around rate limits. Its agent system supports both built-in Python agents (the default code-puppy and agent-creator) and user-defined custom JSON agents, plus MCP servers, DBOS durable execution, AGENTS.md rules, and custom slash commands. The project commits to zero telemetry and zero prompt logging, with an option to run fully locally.
In a terminal, Code Puppy starts via uvx code-puppy -i, reads model configuration from ~/.code_puppy/extra_models., and connects to configured LLM providers. During an interactive session it uses filesystem tools (list_files, read_file, grep, create_file, edit, replace_in_file, apply_patch, delete_snippet, delete_file), agent_run_shell_command for shell execution, and agent_share_your_reasoning to explain its thinking. Users switch models with /model, switch agents with /agent (built-ins like code-puppy and agent-creator, or custom JSON agents in ~/.code_puppy/agents/), add models from models.dev via /add_model, manage MCP servers with /mcp, and toggle DBOS durable execution with /dbos, which checkpoints agent inputs, LLM responses, MCP calls, and tool calls for crash recovery. It loads AGENTS.md rules in priority order (~/.code_puppy/AGENTS.md, .code_puppy/AGENTS.md, ./AGENTS.md), runs custom slash commands from .claude/commands/ or similar directories, and can rotate across multiple API keys configured in extra_models. via round-robin.
- A developer who prefers working in a CLI over an IDE and wants an AI agent that directly edits files and runs commands in their repo.
- A user frustrated by price hikes and restricted model access in subscription tools like Windsurf or Cursor who wants an open-source alternative.
- A team with multiple API keys across providers (e.g., several Cerebras keys) that wants round-robin distribution to stay within rate limits.
- An engineer running long agent tasks who needs durability and resumability, enabled via the DBOS integration with checkpointed LLM, tool, and MCP calls.
- A privacy-conscious developer who runs Code Puppy against a local VLLM/SGLang/Llama.cpp endpoint so no data leaves their network.
- A user who wants to build and share specialized coding agents (code reviewer, Python tutor, DevOps helper) with custom system prompts and restricted tool access, without writing Python, via the JSON agent schema.
What are this agent's strengths and limitations?
- Fully open source (MIT) with a structural privacy commitment: zero telemetry, zero prompt logging, zero third-party sharing, and a documented fully-local option.
- Broad multi-provider support via models.dev integration: 65+ providers, 1000+ models, plus built-in providers (Synthetic, Cerebras, OpenAI, Google, Anthropic), Meta Muse OAuth, and Ollama for local models.
- Round-robin model distribution and custom endpoint timeouts help work around rate limits and flaky endpoints.
- Durable execution via DBOS checkpointing can recover long agent runs after crashes (agent inputs, LLM responses, MCP and tool calls).
- Extensible agent system: schema-validated JSON agents without Python, or Python agents inheriting BaseAgent; MCP server support and AGENTS.md rules.
- Cross-platform: documented support for macOS, Linux, Windows, and Android (Termux).
- Requires Python 3.11+ and the uv/pipx toolchain; the uvx-based workflow adds setup friction for developers unfamiliar with Python tooling.
- The 39 documented OpenAI-compatible providers are 'automatically configured but not tested thoroughly', and models without tool calling get a major warning because they cannot use the file/shell tools.
- Full functionality requires provider API keys (OpenAI, Gemini, Cerebras, Anthropic, Ollama) — an ongoing cost and configuration burden.
- Android/Termux first runs may take 10-20 minutes compiling packages like pydantic-core and cryptography, and Playwright browser tools are not installed.
- The README frames the project as an angry reaction to Windsurf/Cursor — there is no documented enterprise support, SLA, or backing, as it is a solo project with no corporate or investor backing.
How do you install or deploy this agent?
Prerequisites: Python 3.11+ and at least one configured provider API key (e.g., OPENAI_API_KEY, Gemini/Google, Cerebras, Anthropic, or a local Ollama endpoint).
macOS / Linux (uv recommended):
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx code-puppyWindows (PowerShell as Admin):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uvx code-puppy (or install as a global tool for better Ctrl+C/Ctrl+X shortcut support)Android (Termux):
pkg update && pkg install python rust ripgrep libjpeg-turbo git
python -m pip install pipx && pipx ensurepath
pipx run code-puppyOptional durable-execution extra:
pip install "code-puppy[durable]"First invocation: uvx code-puppy -iHow do you use this agent?
- Start an interactive session with
uvx code-puppy -i. - Set provider key environment variables (e.g., OPENAI_API_KEY, GROQ_API_KEY, XAI_API_KEY) or define custom/round-robin models in
~/.code_puppy/extra_models.. - Use
/modelto pick a model; use/add_modelto browse 65+ providers from models.dev. - Describe your coding task in natural language; the agent uses its file, grep, edit, patch, and shell tools to read your repo, modify code, and run commands.
- Use
/agent <name>to switch agents, or/agent agent-creatorto build a new JSON agent. - Manage MCP servers with
/mcp, enable durable execution with/dbos on, and trim message history with/truncate <N>. - Define project coding standards in
~/.code_puppy/AGENTS.mdor a projectAGENTS.md; drop custom slash commands into.claude/commands/,.github/prompts/, or.agents/commands/.
How does this agent compare with similar options?
The README explicitly positions Code Puppy as an open-source, privacy-first, terminal-based alternative to Windsurf and Cursor, stating the project was coded 'angrily in reaction to Windsurf and Cursor removing access to models and raising prices.' Unlike those subscription IDEs, Code Puppy runs in any terminal, brings your own models, and can point at local servers.
FAQ
Does Code Puppy collect my code or usage data?
What models can I use, and what API keys do I need?
What happens if a long agent run crashes mid-way?
How do I create my own specialized agent?
/agent agent-creator in a session for guided JSON agent creation, or manually place a *-agent. file in ~/.code_puppy/agents/ with name, description, system_prompt, tools, and optional fields like model and model_settings. Python agents can also be added by subclassing BaseAgent in code_puppy/agents/.