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

## Installation

### UV (Recommended)

#### macOS / Linux

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

uvx code-puppy

Windows

On Windows, we recommend installing code-puppy as a global tool for the best experience with keyboard shortcuts (Ctrl+C/Ctrl+X cancellation):

# Install UV if you don't have it (run in PowerShell as Admin)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uvx code-puppy

Android (Termux)

Android support uses Termux's native build toolchain because many Python packages do not publish Android wheels. Install the required system packages first:

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

ripgrep provides the native rg executable used for file discovery. libjpeg-turbo provides the headers Pillow needs when pip builds it from source. The first run may spend 10–20 minutes compiling packages such as pydantic-core and cryptography; later runs reuse pipx's cached environment for up to 14 days.

Run the released package:

pipx run code-puppy

To run a source checkout instead, use an editable persistent installation:

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

After a git pull, Python source changes are available immediately. Run pipx reinstall code-puppy only when project dependencies change. Playwright-backed browser tools are not installed on Android.

Optional: DBOS durable execution

Code Puppy ships with an optional DBOS-backed durable-execution plugin that survives crashes and lets you resume long agent runs. It's off by default in the dependency tree — install the durable extra to opt in:

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

Then toggle it from inside the app via /dbos on (and restart). Use /dbos status to check, /dbos off to disable.

Changelog (By Kittylog!)

📋 View the full changelog on Kittylog

Usage

HOT NEW FEATURE: Speculative Tool Execution (Ctrl+X Ctrl+S)

The model's tool calls start running while it is still typing them.

Press Ctrl+X Ctrl+S in the prompt to flip it on (it persists as enable_speculative_code_mode in puppy.cfg; /set enable_speculative_code_mode true works too). Every agent, main or sub-agent, then gets a single run_code tool: a persistent, sandboxed Python REPL where every other tool the agent has (reads, shell, MCP servers, plugin tools) is an async function. create_file and replace_in_file stay native so edits keep their normal review flow.

Two things happen as the snippet streams in:

• Speculation. read_file, grep, and list_files calls with literal arguments launch the moment their line closes. By the time the snippet is finished, most of the reads already are.
• Eager execution. Every other statement (a sleep 2, a test run, a curl) executes as soon as it closes, before generation ends.

A pinned row above the prompt keeps score for the session:

Speculation  29 hits · 0 misses · 0 wasted    saved ≥ 7.0s

saved is a lower bound on tool latency hidden behind the model's own typing — speculative and eager time summed into that one total. Press the chord again to go back to plain tool calls. Off by default; full details in docs/SPECULATION_STATUS.md.

Meta Muse OAuth

Code Puppy can use the same Meta account login as Muse Code. If Muse is already logged in, its credential at ~/.config/muse/auth.json is detected automatically. You can also authenticate directly from Code Puppy:

/meta-auth       # approve a device code with your Meta account
/meta-status     # show the credential source and available Muse models
/meta-logout     # remove only Code Puppy's saved Meta credential

Meta models are registered with a meta- prefix, including meta-muse-spark-1.2-contributor and meta-muse-spark-1.2. META_API_KEY remains supported and takes precedence over saved OAuth credentials.

Adding Models from models.dev 🆕

While there are several models configured right out of the box from providers like Synthetic, Cerebras, OpenAI, Google, and Anthropic, Code Puppy integrates with models.dev to let you browse and add models from 65+ providers with a single command:

/add_model

This opens an interactive TUI where you can: - Browse providers - See all available AI providers (OpenAI, Anthropic, Groq, Mistral, xAI, Cohere, Perplexity, DeepInfra, and many more) - Preview model details - View capabilities, pricing, context length, and features - One-click add - Automatically configures the model with correct endpoints and API keys

Live API with Offline Fallback

The /add_model command fetches the latest model data from models.dev in real-time. If the API is unavailable, it falls back to a bundled database:

📡 Fetched latest models from models.dev     # Live API
📦 Using bundled models database              # Offline fallback

Supported Providers

Code Puppy integrates with https://models.dev giving you access to 65 providers and >1000 different model offerings.

There are 39+ additional providers that already have OpenAI-compatible APIs configured in models.dev!

These providers are automatically configured with correct OpenAI-compatible endpoints, but have not been tested thoroughly:

Smart Warnings

• ⚠️ Unsupported Providers - Providers like Amazon Bedrock and Google Vertex that require special authentication are clearly marked
• ⚠️ No Tool Calling - Models without tool calling support show a big warning since they can't use Code Puppy's file/shell tools

Durable Execution

Code Puppy now supports DBOS 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 false to disable (enabled by default)

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. 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: CRITICAL, 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. - DBOS_APP_VERSION: If set, Code Puppy uses it as the [DBOS application version](https://docs.dbos.dev/architecture#application-and-workflow-versi