code_puppy AGENTS.md

Contributing to Code Puppy

Golden rule: nearly all new functionality should be a plugin in the code_puppy_core_plugins repository that hooks into core via code_puppy/callbacks.py. Don't edit code_puppy/command_line/.

How Plugins Work

Plugins are discovered from three tiers, loaded in order:

Tier	Location	When to use
Builtin	code_puppy_core_plugins/<name>/register_callbacks.py	Official package discovered via Python entry points
User	~/.code_puppy/plugins/<name>/register_callbacks.py	Personal plugins, applied to every project
Project	<CWD>/.code_puppy/plugins/<name>/register_callbacks.py	Repo-specific plugins, shared with your team via git

All three tiers use the same pattern — drop a register_callbacks.py in a named subdirectory:

from code_puppy.callbacks import register_callback

def _on_startup():
    print("my_feature loaded!")

register_callback("startup", _on_startup)

That's it. The plugin loader auto-discovers register_callbacks.py in subdirs.

Project Plugins

Project plugins live at <CWD>/.code_puppy/plugins/<name>/register_callbacks.py. This mirrors the project-level discovery already used by agents (<CWD>/.code_puppy/agents/) and skills (<CWD>/.code_puppy/skills/).

Key details:

• Directory must be created intentionally. Code Puppy will never auto-create .code_puppy/plugins/ — your team opts in by creating it.
• Disabled by default (trust gate). Project plugins run arbitrary repo code at import time, so none load until the user accepts them in the /plugins TUI ceremony (select → Enter → type trust); accepted plugins hot-load with no restart. Trust is a SHA-256 of the plugin dir, stored user-side in ~/.code_puppy/trusted_plugins.json and scoped to the project path — any file change reverts the plugin to untrusted, and everything else fails closed. /plugins revoke <name> removes trust. Full security model: code_puppy/plugins/trust.py.
• Keep runtime state out of the plugin dir — writing state (SQLite, caches, logs) next to the code self-tampers the hash and demands re-acceptance every boot. Use ~/.code_puppy/ like builtin plugins do, or a dot-path (e.g. .state/), which is excluded from hashing.
• Load order is builtin → user → project. Project plugins load last, giving them highest precedence for override-style hooks.
• Project wins on name collision. If a project plugin shares a name with a user plugin, only the project copy loads (the user plugin is skipped). This matches how agents deduplicate — discover_json_agents() overwrites user agents with project agents of the same name. A warning is logged when a project plugin shadows a builtin.
• Module namespace isolation. Project plugins use project_plugins.<name>.register_callbacks in sys.modules, so they never collide with user plugins at the import level.