buddy
CLAUDE.md1 starsChanged 15 days agoMITView on GitHub
Professor's marketplace installs main of this repo, and main reaches every user at their next plugin update: a hook that throws or blocks breaks the prompt line of everyone who installed it.
- Reads credentials
In this repositoryOne other file it gives its agents.
- mirrorSkill
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 43
When that pull request merges, publish.yml's publish job tags the merge commit buddy--v{X.Y.Z} and publishes the GitHub release from the …
- Very specific: line 59
Only a /buddy question, or commentAfterEachTurn, suggestNextPrompt or promptWhenIdle when on, calls a model.
- Very specific: line 72
Every merge into main publishes: the version moves past main's, and a pre-release version (-alpha) is bumped to the real release version in …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
buddy — a Claude Code function-hooks plugin: an ASCII companion above the prompt that reacts to the work and answers /buddy questions
Professor's marketplace installs main of this repo, and main reaches every user at their next plugin update: a hook that throws or blocks breaks the prompt line of everyone who installed it.
Vocabulary
- behavioural spec: what buddy does, its commands, options and character fields ·
README.md - plugin directory: everything that installs and nothing else ·
plugins/buddy/ - adapter: the only file that touches
$, its wiring grouped by event ·plugins/buddy/hooks/buddy.tsx - engine: every decision, as pure modules ·
plugins/buddy/src/ - character: one JSON file per id ·
plugins/buddy/characters/{id}.json· contractplugins/buddy/schema/character.schema.json, guideCONTRIBUTING.md - manifest:
plugin.json, which declares nouserConfig, andicon.svg·plugins/buddy/.claude-plugin/ - config file: every option, one flat JSON object ·
${XDG_CONFIG_HOME:-$HOME/.config}/buddy/config.json· parsed byconfigFilePath,parseConfigFileandresolveOptionsinplugins/buddy/src/options.ts, exampleconfig.example.json - unit tests: one vitest file per engine concern ·
tests/ - hook tests: function-hook tests on the testing kit of the
claude-codemodule;claude plugin testrequires them inside the plugin directory ·plugins/buddy/tests/ - plugin API: every hook's shape; grep it before using an event ·
types/claude-code.d.ts, tracked, the declarations Claude Code writes into a loaded plugin's.claude-plugin/types/claude-code/index.d.ts; refresh it by copying a newer one over it - live proof: a real Haiku session driven in tmux ·
scripts/live-proof.sh - live configuration proof: five sessions over option sets, buddy on opus low, each turn's time and tokens in a report ·
scripts/live-configs.sh, helpers shared inscripts/live-lib.sh - release check: the version agrees everywhere and the CHANGELOG section is dated ·
scripts/release-check.sh - CI: the gates on a pull request into
main, and the GitHub release when it merges ·.github/workflows/ci.yml,.github/workflows/publish.yml - repo agents:
gitter, the only git writer ·.claude/agents/
Runtime
Claude Code
- Function hooks run only with
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1: the hook tests,npm run validate:pluginand a real session all need it. - The
AbovePromptsite is raised in the terminal and the desktop app only; VS Code and mobile never raise it, which the README states and the adapter does not work around. - Options come from the config file alone:
XDG_CONFIG_HOMEwhen set and absolute, else$HOME/.configwhenHOMEis absolute, thenbuddy/config.json; read once at session start by the adapter'sreadConfigFile, never again. A missing file gives the defaults silently; an unreadable or invalid file, an unknown key or a wrong-typed or out-of-range value is one named warning each, that key's default applies and the valid keys still apply. No environment variable and nopluginConfigsentry sets an option: an oldpluginConfigs["buddy@..."]entry is found through$.settings.readper source (Claude Code handsregisteronly declared options, and the manifest declares none) and is one warning naming its keys and the file, its values never applied. Live scripts write$RUN/xdg/buddy/config.jsonand launch with thatXDG_CONFIG_HOME(live_buddy_configinscripts/live-lib.sh). - Migrating from
pluginConfigs["buddy@..."](before 3.0.0): remove the entry fromsettings.jsonand put the same keys, flat, in the config file.
Local
npm test(vitest, thenclaude plugin test plugins/buddy),npm run typecheckandnpm run validate:plugin(root and plugin,--strict) pass before a commit.- Targeted runs:
npx vitest run tests/{concern}.test.tsruns one unit file; the hook tests have no targeted runner (claude plugin testtakes only a folder and runs every file in it, andplugins/buddy/tests/holds one file of two to four minutes), sonpm run test:hooksruns once, at the end of a change, never per edit. npm run liveruns the live proof andnpm run live:configsthe configuration proof, both with--plugin-dir plugins/buddy; run both after any change to the adapter.npm run release:checkproves a release's versions and CHANGELOG section.make release-checkruns exactly the checks CI runs on a pull request intomain(make check, thenmake releaseagainst the localorigin/main, sogit fetch origin mainfirst); Node 22 through mise.
CI
.github/workflows/ci.ymland.github/workflows/publish.ymlare the only workflows; no CI runs on a push to any branch. On a pull request intomain,ci.yml'scheckjob runsmake check(the three gates) on Linux and macOS, itsreleasejob runsmake release(the release check with the version moved pastmain's, and non-empty CHANGELOG notes), and itscijob passes only when every one succeeded.- When that pull request merges,
publish.yml'spublishjob tags the merge commitbuddy--v{X.Y.Z}and publishes the GitHub release from the CHANGELOG section; it fails when the tag already exists.
Rules
Publication
- NEVER a machine-absolute path (under
/Users,/homeor/private), personal data or a private project name in a tracked file. - NEVER push code or cut a release without the owner's ask; a README or marketing commit on
developis pushed as soon as it is committed. mainMUST move only by merging thedevelop → mainpull request, with a merge commit and never a squash, so both branches share one history.
Engine
- A new behaviour lands in the engine as a pure function with a test watched failing first; the adapter only wires it.
$is passed only to functions declared at the top level of the adapter and always spelled$.noun.event(...), and$.envnames are string literals (the adapter reads onlyHOME,XDG_CONFIG_HOME,CLAUDE_CONFIG_DIR,PLUGIN_LOG_DIRandTMPDIR): otherwise Claude Code loads the module with zero hooks, andnpm run validate:pluginreports it.- Every hook catches, logs
{what} failed: {err}throughsay(Claude Code names the plugin on a command's reply, never on a$.ui.logtranscript line, sonotice()addsbuddy:; the debug log's copy then readsbuddy: buddy:, accepted, as$.ui.loghas no transcript-only sink), and returnsnext(e)or the original result. - A failure shows on screen: a missing or invalid character draws the duck with a bubble naming the error and pointing at the personality picker (ctrl+x t in
/buddy), which lists it as(invalid). - Only a
/buddyquestion, orcommentAfterEachTurn,suggestNextPromptorpromptWhenIdlewhen on, calls a model; walking, reactions and every other command stay local. - Dev files live outside the plugin directory, which installs whole.
Characters
- A built-in character carries
"$schema": "../schema/character.schema.json", validates against it, and its art and persona are original. - A missing line pool falls back to the engine's neutral pool, in no character's voice.
- A change to a command, an option or a character field moves
README.md,CONTRIBUTING.mdand the schema in the same commit; an option's also movesconfig.example.json, itsDEFAULTSrow and its README option row.
Branches and releases
developis the default branch: every change lands there, by a commit or a pull request. It is protected by the rulesetdevelop keeps its history: never force-push or delete it.mainis protected by the rulesetmain is release-only: it merges only aftercipasses, never by a direct push and never by an admin override.- Every merge into
mainpublishes: the version moves pastmain's, and a pre-release version (-alpha) is bumped to the real release version in that pull request. - A version bump moves
plugins/buddy/.claude-plugin/plugin.json,package.jsonand the README badge together, and turns## [Unreleased]inCHANGELOG.mdinto## [X.Y.Z] — {date}; installed copies update only on a new version. - Semantic versioning: a fix is a patch; a new option, behaviour or built-in character is a minor; a renamed or removed option, command or character field, or a moved option home, is a major, and its CHANGELOG entry says how to migrate.
- A release is
gitter's RELEASE phase: bump the version and the dated CHANGELOG section ondevelop,git fetch origin mainthenmake release-check, open thedevelop → mainpull request, merge it onceciis green; the merge is the release,publish.ymltags and publishes it, and no tag is ever pushed by hand. - Git writes go through
gitter,.claude/agents/gitter.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

