Golden rule: Code Puppy 1.0 is a distribution of
pydantic-ai-pax("pax"; namedpydantic-clai2until 2026-11-19). The runtime owns the agent loop, terminal UI, sessions, models, MCP and plugins. Do not reimplement any of that here. New behaviour is a paxPlugin, apydantic-ai-harnesscapability, or an upstream change.
Plan and status: docs/upgrade/code_puppy_1_0_rewrite_plan.md.
main still ships 0.0.x; nothing here applies to it.
| Path | Holds |
|---|---|
code_puppy/main.py |
Entry point for pup / code-puppy; import-light until the splash is up |
code_puppy/identity.py |
Names and directories. Stdlib-only |
code_puppy/distribution.py |
Every replacement of a pax name. Nowhere else |
code_puppy/update.py |
/update, pup update: PyPI lookup, version rules, wording |
code_puppy/branding.py, _art.py |
Banner, welcome lines, splash art |
code_puppy/migrate/ |
One-time carry-over of a 0.0.x setup |
code_puppy/legacy_store.py |
puppy.db: Code Puppy's own SQLite file |
code_puppy/api_keys.py |
Exports saved API keys for model providers |
code_puppy/legacy_sessions.py |
0.0.x sessions as an import source for /resume |
code_puppy/builtin_plugins.py |
Plugin declarations Code Puppy ships |
code_puppy/personality.py |
The personality plugin: the main agent's name, tone and opinions |
code_puppy/first_run.py |
First interactive launch: asks the puppy's and owner's names, once |
code_puppy/compat/ |
Bridge that runs 0.0.x plugins |
code_puppy/callbacks.py, config.py, messaging/, i18n/, plugins/ |
0.0.x import paths, kept as thin facades |
- One pin.
pydantic-ai-paxis pinned exactly and carries the harness andpydantic-ai-slimpins. Never add a direct pin for either. It is required with every extra it offers (the/sandboxproviders,typesafe), so nothing answers "support is not installed";tests/test_optional_support.pyfails when pax adds one.pydantic-clai2is now only an alias package (import pydantic_clai2resolves topydantic_ai_pax). It is a dependency solely becausepydantic-claude-code0.7.x imports the old name; pin it to pax's version, importpydantic_ai_paxin our code, and drop it when that plugin moves. Claude Code models come frompydantic-claude-code. Do not "fix" that topydantic-ai-claude-code: that PyPI name is someone else's project. - Replacements live in
distribution.py. If you must replace another pax name, add it there with_replace, add a row to the table in its docstring, and add it toREPLACEDintests/test_distribution_contract.py. Each one is debt: prefer an upstream seam. - The 0.0.x plugin API is frozen.
callbacks.py,config.py,messaging/,i18n/andplugins/exist so old plugins import. Do not add hooks or helpers to them, and do not import them from new code. - Optional tools load on demand. Anything a plugin adds for the model
(tools, MCP servers, capabilities) is created with
defer_loading=True. - Legacy files are read-only. The migration never modifies, renames or deletes a 0.0.x file, and never overrides a value already set in 1.0.
- Startup stays light.
identity.pyand the top ofmain.pyimport nothing from the runtime. Heavy imports happen under the splash. - Fail gracefully. A broken plugin or a bad legacy file is reported and
skipped. It never stops
pupfrom starting. - Tests never touch the user's machine.
tests/conftest.pyredirects the home directory and disables the OS keyring for every test. Keep it that way. - 600-line cap per file. Split by responsibility, not to hit the number.
- Always run linters:
uv run ruff check --fix,uv run ruff format ., thenuv run pytest. - NEVER ALLOW A CLAUDE CO-AUTHOR COMMIT.
- Keep this file under 10,000 characters. It is sent to the model with
every request.
tests/test_agents_md_size.pyenforces the budget.
v1publishes1.0.0rcNpre-releases;mainpublishes0.0.x.uvx code-puppyresolves to the newest stable release, so 0.0.x users are unaffected until 1.0.0 ships.v1bumps withuv version --bump rc. Never--bump patchonv1: it turns1.0.0rc1into a stable1.0.1.scripts/check_release_version.pyfails the publish job if that happens.- A release candidate can only depend on packages released to PyPI.
Between runtime releases
v1may build against a commit of pydantic-aimain:[tool.uv.sources]inpyproject.toml, every package at onerev. The release guard refuses to publish in that state. Restorepydantic-ai-pax==X.Y.Zand delete the sources first. - Pushing to
v1ormainpublishes. Do not push without being asked.
Use the pax Plugin API (pydantic_ai_pax/_docs/PLUGINS.md in the installed
package). A plugin Code Puppy ships gets a declaration in
code_puppy/builtin_plugins.py. A user drops a file or package into
~/.code_puppy/plugins/.
A folder with a register_callbacks.py is a 0.0.x plugin. The bridge loads
three tiers: the code_puppy.plugins entry-point group, the user's plugins
folder, and <repo>/.code_puppy/plugins/ once trusted with
/puppy-plugins trust NAME. Trust is a SHA-256 of the plugin folder; any edit
revokes it.
code_puppy/callbacks.py lists all 77 hook names in three tiers:
- Supported (15): fire at the equivalent runtime moment.
- Accepted and removed (62): register without error, never fire.
/puppy-pluginsshows which plugins rely on them.
Tool hooks receive 0.0.x tool names (agent_run_shell_command, create_file);
the mapping is in code_puppy/compat/tools.py. Update it when the runtime
renames a tool, or guards written against the old names stop matching.
- Windows: the agent's commands run in PowerShell, not
sh(the runtime'sWindowsWorkspace). No interactive session with a real model has been run yet. - JSON agents, the
/agentcommand and ports of the retired core plugins are not built yet. See the plan.