choirboy-prompt

Persistent project memory and automatic agent-authored artifacts

Read this in other languages
🇺🇸 English · 🇷🇺 Русский · 🇨🇳 简体中文

choirboy-prompt is a production agent-memory plugin. It loads established lore, research, working rules, and validated project dossiers into supported agent runtimes so every new session continues from the same project history.

All model-facing canonical files, research, lifecycle instructions, INDEX files, and dossiers are written in English. Only the user documentation is localized into English, Russian, and Simplified Chinese.

---

How it works

1. Install. ./install.sh finds the agent apps on your machine and registers a hook in each one that fires when a new session starts. Where hooks do not exist, it writes a synchronized managed block into the instruction file; for Grok Bot it prepares a workflow for manual import.
2. Assembly. The fixed lore is prompt.md, security-posture.md, lore.md, user.md, and context/research-index.md, plus validated dossiers when they are ready.
3. Delivery. Claude Code and Codex SessionStart hooks send a short status only. Those harnesses cap or spill hook text, so the status does not include the lore and does not carry a choirboy-delivery marker. The load-context skill supplies the lore when the conversation does not already contain it. Kimi, OpenCode, and Hermes still receive the full plain payload on channels that accept it.
4. Project artifacts. A shipped ready bundle is restored when it still matches the canonical sources. The agent authors or refreshes dossiers only when the user explicitly asks to update Choirboy memory. Stop does not continue the turn to demand that work.
5. Continuity. Stable user-data storage, migration, and structural validation keep the same project memory active across upgrades.

Plugin internals: docs/architecture.en.md.

Supported runtimes

Runtime	Where it goes	Mechanics
Claude Code CLI / Desktop Code	marketplace or ~/.claude/settings.json	short SessionStart status; Stop does not continue the turn; load-context skill carries the lore
Claude Chat / Cowork	custom plugin	load-context skill (Chat has no SessionStart)
Codex	~/.codex/hooks.json	short SessionStart status; Stop does not continue the turn (the installer warns if hooks = false is set in ~/.codex/config.toml)
OpenCode	~/.config/opencode/plugins/agent-plugin.ts	plugin appends current lore and ready artifacts to every model-bound system context, including after compaction
Hermes	~/.hermes/config.yaml	pre_llm_call + consent allowlist, first turn only
Kimi Code 0.39.x	~/.kimi-code/config.toml	SessionStart/PreCompact reset delivery; UserPromptSubmit emits changed plain context; Stop does not continue the turn
Gemini	~/.gemini/GEMINI.md	synchronized lifecycle instruction block
Grok Build	~/.grok/AGENTS.md	synchronized lifecycle instruction block (hook stdout is ignored)
Grok Bot	~/.grokbot/choirboy-context/SKILL.md	workflow for manual import; run @choirboy-context in every new chat
Pi	~/.pi/agent/APPEND_SYSTEM.md	same instruction contract as Gemini, plus the load-context skill
Oh My Pi (omp)	~/.omp/agent/AGENTS.md	same instruction contract as Gemini, plus the load-context skill
llama-server UI	~/.config/llama.cpp/choirboy-ui.json	default systemMessage with the same contract; pass --ui-config-file

Install

You need git, bash, and python3. Check: git --version && python3 --version && bash --version.

git clone https://github.com/howdeploy/choirboy-prompt.git
cd choirboy-prompt
./install.sh

Done. Open a new session. Claude Code and Codex show a short memory status and load the lore through the load-context skill. Kimi, OpenCode, and Hermes receive the full plain payload.

• Selected apps only: ./install.sh --target claude,codex
• Per-runtime status: ./install.sh --list (stale means a managed registration needs synchronization)
• Rollback: ./install.sh --uninstall (timestamped *.bak.* backups stay next to the configs)
• Permission denied on launch: chmod +x install.sh and retry

Project artifacts live outside a manual checkout. Location precedence is CHOIRBOY_ARTIFACTS_DIR → ${CLAUDE_PLUGIN_DATA}/project-artifacts → ${XDG_DATA_HOME}/choirboy-prompt/project-artifacts → ~/.local/share/choirboy-prompt/project-artifacts. Re-running the installer synchronizes owned registrations and, when that stable root is empty, migrates an authored bundle from an older checkout without overwriting it. A private migration record makes an interrupted bundle copy resume instead of exposing a partial INDEX/manifest/dossier set.

Special cases — manual workflow import for Grok Bot, install via Claude marketplace / Desktop / Chat / Cowork, Windows and WSL — are covered in docs/installer.en.md. Do not combine the marketplace plugin with ./install.sh --target claude: the lore would be loaded twice.

Fill in your own files

The repository ships its canonical lore bundle. For your deployment, replace it with verified memory from your own project right in the clone: install.sh points at the working copy, so edits are picked up by the next session. No forking or copying is needed.

File	What to write
prompt.md	work rules, priorities, explicit boundaries
security-posture.md	security frame and disclosure rules
user.md	only durable collaboration preferences
lore.md	real projects, decisions, outcomes, and lessons
research/NN-topic.md	one decision per file: question, evidence, options, decision, risks, revisit conditions
context/research-index.md	one line per research document

Order of work:

1. Rewrite prompt.md, user.md, lore.md for your project.
2. One research/NN-topic.md per decision, plus a line in the index.
3. Rebuild and verify: python3 scripts/build-context.py && bash scripts/test.sh.

Full guide with templates and the quality gate: docs/authoring.en.md.

Why this exists

Agent runtimes normally start each conversation without the full operational history of a project. Re-explaining decisions wastes time and produces drift. This plugin turns the repository's canonical lore and agent-authored dossiers into an automatically loaded, validated memory layer shared by every supported runtime. Installation, migration, diagnostics, and rollback remain explicit and reproducible.

Documentation

Document	Contents
Authoring your memory	Mandatory workflow and templates for lore and research
Architecture	Repo tree, payload anatomy, formats, Hermes protocol
Installer	All install paths, targets, markers, backups, edge cases
Troubleshooting	Delivery diagnostics, delivery markers, Windows/SSH/Cloud/WSL
Security and disclosure	Security frame, sanitization checklist, responsible disclosure
Testing	Hook and installer checks, ad-hoc suite

Known limitations

• Grok Bot: requires a one-time workflow import and an explicit @choirboy-context invocation in every new conversation.
• Gemini, Grok Build, and --instructions have no native delivery hook: their managed instruction block asks the agent to run the lifecycle command. A normal installer rerun synchronizes that block; no uninstall/reinstall cycle is required.
• Hermes first-turn dedup is a state file in /tmp without locks; parallel starts can race.
• Claude Chat does not run SessionStart — there the skill loads the lore manually; Cloud/WSL/SSH nuances are in troubleshooting.

---

License

MIT. See LICENSE.

---

Innocent as a choirboy.