code_puppy: a terminal code agent that streams tool calls while the model still types

A code agent that lives in the terminal instead of the editor

Code Puppy is an AI code generation agent with a terminal prompt, described in the README as sassy and built as a reaction to Windsurf and Cursor removing access to models and raising prices. The repository is Python, licensed MIT, and the pyproject.toml declares version 0.0.938 with requires-python ">=3.11,<3.15". The dependency list is the interesting part: it pulls in pydantic-ai-slim with the openai, anthropic and mcp extras, plus the pydantic-ai-harness code-mode package, typer for the command line, rich for terminal output, and mcp for Model Context Protocol servers. That combination explains the shape of the project. It is not a thin wrapper that sends a diff to a hosted editing service. It runs an agent loop locally, and the tools that loop calls are ordinary Python functions on your machine.

The README also notes the motivation plainly: the author wrote it angrily in reaction to pricing changes, and remarks that you could run 50 code puppies at once. That is marketing tone rather than a technical claim, and the README does not document any multi-agent scheduling mechanism, so treat the parallelism remark as a joke rather than a feature list. What is verifiable is the architecture: an agent loop built on Pydantic AI, a terminal front end, and a set of native tools for reading files, searching, listing directories and making edits.

Starting in one command with uvx

The quick start in the README is a single command, and it is worth using the interactive flag on the first run because the agent asks for provider keys once it starts.

uvx code-puppy -i

The README recommends UV, and on macOS and Linux the documented way to get it is a shell installer followed by the same uvx invocation:

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

uvx code-puppy

Because uvx resolves the package on demand, there is no clone step and no virtualenv to manage for a trial. The Windows path in the README is a PowerShell install of UV followed by `uvx code-puppy`, and the README adds a Windows-specific note: on Windows they recommend installing the package as a global tool so the Ctrl+C and Ctrl+X cancellation shortcuts behave properly. That is a platform caveat worth reading before you assume identical behaviour across operating systems.

For a source checkout, the README documents an editable pipx install instead:

git clone https://github.com/mpfaffenberger/code_puppy.git
cd code_puppy
pipx install --editable .
code-puppy

After a `git pull`, the README says Python source changes are available immediately, and `pipx reinstall code-puppy` is only needed when project dependencies change. The same section notes that Playwright-backed browser tools are not installed on Android, which is the first sign that this project has platform-specific gaps rather than a uniform install.

Android needs its own toolchain and a long first compile

The Android instructions are the most concrete part of the README and show what the dependency tree costs on a platform without prebuilt wheels. Because many Python packages do not publish Android wheels, Termux uses its native build toolchain, and the README asks for a specific package set:

pkg update
pkg install python rust ripgrep libjpeg-turbo git
python -m pip install pipx
pipx ensurepath
export PATH="$HOME/.local/bin:$PATH"  # Makes pipx apps available immediately

Each dependency has a stated reason. ripgrep provides the native `rg` executable used for file discovery, and libjpeg-turbo provides the headers Pillow needs when pip builds it from source. The README is candid about the cost: the first run may spend ten to twenty minutes compiling packages such as pydantic-core and cryptography, while later runs reuse the pipx cached environment for up to fourteen days. The released package is then run with `pipx run code-puppy`. That cache window is the operational fact to plan around: an Android user who comes back after more than two weeks pays the compile again.

There is a related trap for every platform. The pyproject.toml pins ripgrep to version 14.1.0 for all systems except Android, and adds playwright at version 1.40.0 or newer on the same exclusion. A reader who assumes the search and browser tools are present everywhere will find file discovery broken on Android unless the Termux package set was installed first.

API keys live in .env, and .env wins over puppy.cfg

Code Puppy talks to whichever model provider you configure, and the .env.example file in the repository shows the full set of supported variables. The file opens with a note that it takes priority over ~/.code_puppy/puppy.cfg, which resolves an ambiguity that would otherwise cause confusion when a key seems ignored:

# OpenAI API Key
# OPENAI_API_KEY=sk-...

# Google Gemini API Key
# GEMINI_API_KEY=...

# Anthropic (Claude) API Key
# ANTHROPIC_API_KEY=...

The same file also lists CEREBRAS_API_KEY, OPENROUTER_API_KEY, ZAI_API_KEY, SYN_API_KEY, and the Azure pair AZURE_OPENAI_API_KEY with AZURE_OPENAI_ENDPOINT. That breadth is the main argument for the project over a single-provider assistant: switching a model is a configuration change rather than a code change. The cost is that you now hold credentials for several vendors in one file, and the priority rule means an old .env can silently shadow newer settings in puppy.cfg.

The optional durable execution path follows the same configuration style. A DBOS-backed plugin is off by default in the dependency tree and is enabled by installing the extra:

pip install "code-puppy[durable]"
# or
uv pip install "code-puppy[durable]"

Once installed, the README says to toggle it from inside the app with `/dbos on` and restart, with `/dbos status` to check and `/dbos off` to disable. The plugin exists so long agent runs can resume after a crash, which is a genuine gap in most agent loops, and it stays off until you ask for it.

Speculative execution runs statements before the model finishes typing

This is the feature that separates Code Puppy from a plain chat loop with tools, and it is also the one that changes the risk profile. The README describes speculative tool execution behind the Ctrl+X Ctrl+S chord. When enabled, every agent, main or sub-agent, receives a single `run_code` tool: a persistent, sandboxed Python REPL in which the other tools (reads, shell, MCP servers, plugin tools) are exposed as async functions. `create_file` and `replace_in_file` stay native so edits keep their normal review flow.

Two behaviours run in parallel with generation. Speculation covers `read_file`, `grep` and `list_files` calls with literal arguments: they launch the moment their line closes, so by the end of the snippet most reads are already done. Eager execution covers every other statement, including a sleep, a test run or a curl, and it fires as soon as the statement closes, before generation ends. A status row above the prompt reports the session as hits, misses and wasted time, with a saved figure described as a lower bound on tool latency hidden behind the model's typing.

The design point for a reviewer is the split between tool types. Reads and greps are idempotent, so running them early costs little. A shell command or an HTTP call is not, which is why eager execution is the part to think about before enabling this on a machine that matters. The setting persists as `enable_speculative_code_mode` in puppy.cfg, and `/set enable_speculative_code_mode true` works as an alternative. The README points to docs/SPECULATION_STATUS.md for full detail and says the chord toggles back to plain tool calls.

Where Code Puppy is the wrong tool

The honest limits are visible in the dependency list and the README's own hedges. It requires Python 3.11 or newer, so a locked-down corporate Python 3.10 estate cannot run it. It needs ripgrep on PATH for file discovery, which means the Android path must install the Termux package first or search breaks. Browser tools are unavailable on Android. There is no HTTP API surface described in the README, only a terminal program and in-app slash commands, so it cannot sit behind a shared web front end the way a hosted assistant can.

The model provider question is also yours to answer. The .env.example lists seven or more vendors, and the README does not describe any bundled or free model tier. Running the agent means your prompts and repository contents travel to whichever provider you configured, and the README's privacy badge is a project claim rather than a technical guarantee.

Compared with a hosted coding assistant, the difference in approach is straightforward. A hosted service owns the sandbox, the model account and the audit trail, and gives you a review surface for diffs. Code Puppy owns none of that: the agent runs on your machine with your keys, the tools are local Python functions, and the plugin model through MCP means you choose which extra capabilities exist. The trade is control and privacy exposure against convenience and governance.

Editorial conclusion

Code Puppy suits developers who want an agentic coding loop they can run from a terminal and extend with MCP servers, and who are comfortable supplying their own API keys in a .env file. It is a poor fit for a team that needs a hosted, audited code service or for anyone unwilling to let an agent edit a working tree, because edits happen through the same tool surface and speculative execution can run a statement before you have read it. Before adopting it, check that your provider keys load from .env as expected, that ripgrep is present for file discovery, and that the speculative chord is left off until you have read docs/SPECULATION_STATUS.md and can turn it off with Ctrl+X Ctrl+S.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mpfaffenberger/code_puppy on GitHub
4. README
5. Releases