Skip to content

Back to the catalog

github.comrepo

choirboy-prompt

choirboy-prompt is a cross-runtime agent-memory plugin that loads project lore, research indexes, and validated dossiers into agent sessions via SessionStart hooks (Claude Code, Codex) or full plain-text payloads (Kimi, OpenCode, Hermes), so new conversations continue from established project history instead of starting cold. It handles installation across multiple agent apps, migration of project artifacts between checkout locations, and includes a build/verify pipeline (build-context.py, test.sh) for authoring canonical lore files like prompt.md, user.md, and lore.md.

TL;DR A plugin that injects persistent project "lore" and dossiers into Claude Code, Codex, and other agent runtimes at session start so agents retain project memory across conversations.
Open original ↗
Document

What it claims

choirboy-prompt (MIT) is an agent-memory plugin that injects a project's canonical lore into new agent sessions across several runtimes. The summary already covers that; what it omits is that delivery is not uniform, and the per-runtime differences are the whole story for anyone deploying it. The canonical files, research, INDEX, and dossiers are all authored in English; only the user documentation is localized (English, Russian, Simplified Chinese).

How it works

The key detail the summary flattens: SessionStart hooks do not all carry the lore.

  • Claude Code and Codex hooks send a short status only — no lore, and deliberately no choirboy-delivery marker — because those harnesses cap or spill hook text. The load-context skill supplies the lore when the conversation doesn't already contain it.
  • Kimi, OpenCode, Hermes receive the full plain-text payload on channels that accept it.
  • Gemini, Grok Build, --instructions have no native delivery hook; a managed instruction block asks the agent to run the lifecycle command. Rerunning the installer re-syncs the block (no uninstall/reinstall needed).
  • Grok Bot requires a one-time manual workflow import plus an explicit @choirboy-context in every new conversation.
  • Claude Chat does not run SessionStart at all — the skill loads lore manually.

The fixed lore set: prompt.md, security-posture.md, lore.md, user.md, context/research-index.md, plus validated dossiers.

How to use it

Needs git, bash, python3.

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

Useful flags: ./install.sh --target claude,codex (selected apps), --list (per-runtime status; stale = registration needs re-sync), --uninstall (leaves timestamped *.bak.* backups).

To deploy your own memory, edit the shipped canonical files in the clone (no fork needed), then:

python3 scripts/build-context.py && bash scripts/test.sh

Artifacts live outside the checkout, resolved by precedence: CHOIRBOY_ARTIFACTS_DIR → ${CLAUDE_PLUGIN_DATA}/project-artifacts → ${XDG_DATA_HOME}/choirboy-prompt/project-artifacts → ~/.local/share/choirboy-prompt/project-artifacts.

Limits

  • Do not combine the Claude marketplace plugin with ./install.sh --target claude — the lore loads twice.
  • Hermes first-turn dedup is an unlocked state file in /tmp; parallel session starts can race.
  • Grok Bot's per-conversation manual invocation makes it materially less automatic than the others — factor this in if it's your target runtime.

Organisations named here

  • Claude Code
  • Hermes
  • Kimi
  • OpenCode

Technologies named here

  • choirboy-prompt
  • install.sh
  • load-context skill
  • scripts/build-context.py
  • scripts/test.sh
  • Claude Code
  • Codex
  • Kimi
  • OpenCode
  • HERMES
  • Grok Bot
  • Gemini
  • Grok Build
  • Claude Chat

Techniques named here

  • SessionStart hook
  • Managed instruction block
  • Explicit dossier authoring
  • Migration record
  • Location precedence for project artifacts

Related in coding-agents