code-puppy-agent
How Code Puppy itself is built — its internal architecture, structure, codebase layout, and source modules. Explains agents, tools, the plugin/callback hook system, models, MCP, sessions and history/context windows, skills (including skill namespaces for large catalogs), slash commands, config, messaging/UI, system-prompt assembly, and i18n. Activate for ANY question about how Code Puppy works internally, why it behaves a certain way, where something lives in the code, how a feature is implemented, or how to navigate, debug, or extend the codebase (add a tool, agent, plugin, command, skill, model, or MCP server).
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 9
- Forks
- 32
01 前言 Front Matter
- name
- code-puppy-agent
- tags
- [ "code-puppy", "architecture", "structure", "internals", "codebase", "source", "how-it-works", "self-awareness", "agents", "tools", "plugins", "hooks", "callbacks", "models", "mcp", "sessions", "history", "skills", "namespaces", "commands", "config", "messaging", "i18n", "extend", "debug", "reference" ]
- author
- code-puppy
- version
- 2.0
- description
- How Code Puppy itself is built — its internal architecture, structure, codebase layout, and source modules. Explains agents, tools, the plugin/callback hook system, models, MCP, sessions and history/context windows, skills (including skill namespaces for large catalogs), slash commands, config, messaging/UI, system-prompt assembly, and i18n. Activate for ANY question about how Code Puppy works internally, why it behaves a certain way, where something lives in the code, how a feature is implemented, or how to navigate, debug, or extend the codebase (add a tool, agent, plugin, command, skill, model, or MCP server).
02 资源文件 8
- 脚本__init__.py182 B
- 参考文档AGENTS_AND_TOOLS.md6.3 KB
- 参考文档MODELS_AND_MCP.md3.4 KB
- 参考文档PLUGINS_AND_CALLBACKS.md8.1 KB
- 脚本register_callbacks.py1.9 KB
- 参考文档SESSIONS_AND_HISTORY.md1.3 KB
- 参考文档SKILLS_SYSTEM.md6.3 KB
- 参考文档SYSTEM_PROMPT_CONFIG_AND_I18N.md8.0 KB
03 SKILL.md 正文
Code Puppy — Architecture & Internals
This skill is a self-awareness document. When activated it teaches the LLM how Code Puppy is structured under the hood so it can navigate the codebase, debug issues, and extend the product without guessing.
Philosophy: Code Puppy is plugin-first. Nearly all new functionality should be a plugin in the separate
code-puppy-core-pluginsrepo that hooks into core viacode_puppy/callbacks.py. Don't editcode_puppy/command_line/or core agent files unless a hook genuinely doesn't exist.
Two repos. Core (the
code-puppypackage) holds the runtime, agents, tools, and the callback engine. Plugins (thecode-puppy-core-pluginspackage, this skill included) ship separately and are discovered throughcode_puppy.pluginsentry points. Paths below startingcode_puppy/are in core; paths startingcode_puppy_core_plugins/are in the plugins repo.
This skill is split across multiple files so activating it doesn't force
the full ~30KB of internals into context on every use — this SKILL.md is
the index. Read the reference file for the topic you actually need;
each one is self-contained and cites real file paths so you can jump
straight to source. All reference files are plain repo paths under
code_puppy_core_plugins/code_puppy_agent/ — read them with read_file.
Layered Architecture
┌──────────────────────────────────────────────────┐
│ TUI / CLI (command_line/, messaging/) │
│ user input → slash commands → agent dispatch │
├──────────────────────────────────────────────────┤
│ Agent Layer (agents/) │
│ BaseAgent → system prompt, tools, history │
│ _builder, _runtime, _compaction, _history │
├──────────────────────────────────────────────────┤
│ Tool Layer (tools/) │
│ TOOL_REGISTRY → register_tools_for_agent() │
├──────────────────────────────────────────────────┤
│ Plugin Layer (callbacks.py + plugins/ loader) │
│ register_callback("hook", fn) at import time │
├──────────────────────────────────────────────────┤
│ Model Layer (model_factory.py, config.py) │
│ ModelFactory → pydantic-ai Model objects │
├──────────────────────────────────────────────────┤
│ pydantic-ai (external) │
│ Agent.run(), streaming, tool schemas │
└──────────────────────────────────────────────────┘
The TUI collects user input. It delegates to the agent manager which
loads the current agent. The agent builds a pydantic-ai Agent with a
system prompt + tool set, then run_with_mcp() streams the LLM response.
Plugins hook into every stage via callbacks.
Reference Map
| File | Read this for |
|---|---|
AGENTS_AND_TOOLS.md |
How agents are structured/discovered (Python, JSON, plugin agents, precedence). How tools get registered and wired to an agent. Async-tool blocking-I/O gotcha. |
PLUGINS_AND_CALLBACKS.md |
Plugin discovery tiers, the callback hook table, in-place tool-result mutation and ordering, a minimal plugin example, and hook-system gotchas (get_model_system_prompt last-write-wins; don't do real work at import time). |
MODELS_AND_MCP.md |
ModelFactory, model config precedence, model types. MCP server lifecycle, agent bindings, and a known gap (MCP servers can't yet provide skills). |
SESSIONS_AND_HISTORY.md |
Message history, context-window compaction, session save/load commands. |
SKILLS_SYSTEM.md |
Skill discovery/activation, bundled-resource-file gotcha for plugin-registered skills, and skill namespaces — how namespace_skill_search groups large skill catalogs and replaces the flat prompt list. |
SYSTEM_PROMPT_CONFIG_AND_I18N.md |
Exact system-prompt assembly order, puppy.cfg + key directories, spill configuration, the messaging bus, and an i18n quick-reference (full guide: docs/I18N.md). |
Don't guess which file has what you need — the table above is exhaustive
for this skill's scope. If a question doesn't map cleanly to one row, it's
probably answered by combining two (e.g. "why did my plugin's prompt
addition get silently dropped" is a PLUGINS_AND_CALLBACKS.md +
SYSTEM_PROMPT_CONFIG_AND_I18N.md question).
Development Conventions
Golden rules
- Plugins over core — if a callback hook exists, use it. Don't edit
command_line/or core agent files. - One
register_callbacks.pyper plugin — register at module scope. - 600-line hard cap per file — split into submodules. (This very skill was split for exactly this reason — it was 632 lines as one file.)
- Fail gracefully — plugins must never crash the app. Wrap external calls in try/except.
- Return
Nonefrom hooks/commands you don't own. - Always run linters —
ruff check --fix,ruff format . - Wrap user-facing strings in
t()/ngettext(seeSYSTEM_PROMPT_CONFIG_AND_I18N.md) — don't hardcode English display text. Model-facing system prompt content is explicitly exempt. - Never allow a Claude co-author commit.
Plugin structure
my_plugin/
├── __init__.py # docstring (can be minimal)
├── register_callbacks.py # entry point: register_callback() calls
├── helpers.py # optional: logic split out
└── README.md # optional: documentation
Zen of Code Puppy
- Simple is better than complex.
- Flat is better than nested.
- If a hook exists for it, use it.
- Files should be readable in one sitting.
- The plugin system is the API surface; the core is the engine.
Quick Reference: Key File Map
| File | Responsibility |
|---|---|
agents/base_agent.py |
Abstract agent base — thin conductor |
agents/_builder.py |
Builds pydantic-ai Agent + MCP wiring |
agents/_runtime.py |
run_with_mcp() — streaming, retries, cancellation |
agents/_compaction.py |
Context summarization |
agents/agent_manager.py |
Agent registry, switching, discovery |
agents/json_agent.py |
JSON-config agent loader |
tools/__init__.py |
TOOL_REGISTRY, register_tools_for_agent() |
plugins/__init__.py |
Plugin loader (builtin → user → project) |
callbacks.py |
Hook engine — 45+ phases |
config.py |
Config read/write, directories, model settings |
model_factory.py |
Model-name → pydantic-ai Model |
mcp_/manager.py |
MCP server lifecycle |
session_storage.py |
Session pickle save/load |
plugins/agent_skills/ |
Skills discovery, activation, UI |
plugins/namespace_skill_search/ |
Namespace grouping + on-demand browse tool for large skill catalogs |
i18n/ |
Internationalization: catalogs, t()/ngettext, locale detection, formatting |
i18n/locales/*.json |
Message catalogs (source of truth: en-US.json) |
pydantic_patches.py |
Startup monkey-patches (clipboard fix, etc.) |
When to use this skill
Activate this skill when you need to:
- Understand how a feature works internally before modifying it
- Create a new plugin and need to know which hooks to use
- Debug an agent, tool, model, skill, or MCP issue
- Navigate the codebase and need to find the right file
- Extend Code Puppy with custom tools, agents, skills, or commands
Then read the specific reference file(s) from the map above — don't try to hold all six in context at once unless the question is genuinely that broad.
04 同仓库更多 Skills
web-retriever
Use before handling web scraping, browser automation, crawling, structured data extraction, authenticated or interactive website workflows, monitoring pages for changes, or website screenshots. Delegates browser work to the web-retriever agent; not for test assertions or visual QA.
qa-kitten
Use before testing a web application's behavior, accessibility, responsive layout, or visual rendering in a real browser. Delegates browser assertions and visual QA to qa-kitten; not for scraping, crawling, or general web retrieval.
create-skill
Create, edit, test, or tune a Code Puppy skill (a SKILL.md with frontmatter and optional references/). Use for /create-skill, "make a skill for X", "turn this into a skill", substantive edits to an existing skill, or "tune description" when a skill doesn't trigger when it should.
herdr-code-puppy
Safely launch Code Puppy siblings and choose prompt versus explicit command input inside a Herdr pane. Activate before controlling siblings.
agent-creator
Use before creating or revising a Code Puppy JSON agent. Delegates schema design, least-privilege tool selection, optional model and MCP bindings, validation, and per-agent Spill configuration to agent-creator.