Rules for changing code, tests, model-facing text and docs in this repo. [test: x] marks a rule that a test
enforces; the others rely on discipline.
- Prettier formats code, JSON and YAML, not Markdown or MDX. Run it only through
scripts/format.sh: the script holds the pinned version. Setup of the pre-commit hook:docs/development.mdx, Format.[test: code.check.mjs] hooks/is the hooks module that Claude Code loads (hooks/hooks.json). Pure helpers go inhooks/protocol.ts,hooks/hints.ts,hooks/functions.ts,hooks/paths.tsandhooks/tools.ts, with no$, so tests call them directly. Anything that uses$goes inhooks/register.tsx, in a function declared at the top of the file: the engine's loader follows$only there, never across an import, and a module that passes$to another file does not load.[test: tsconfig.pure.json fails when a pure helper imports claude-code, register.tsx or a Node module]- Context for the model at session start goes in
hooks/session-start.sh, a command hook inhooks/hooks.json. Claude Code's built-in security module skips a hooks module'sclassic.SessionStart, so a module handler never runs. A set option reaches the script asCLAUDE_PLUGIN_OPTION_<KEY>. - Read the time with
await $.clock.now(), neverDate.now()ornew Date(): a test sets the time withmock.clock.[test: code.check.mjs] - Make each path into
.claude/code-modewith a helper fromhooks/paths.ts:hintsFolder,functionsFolderorcodeModePath. The guard readsguardedDirsthere, so the guard and the loaders name the same folders.[test: code.check.mjs][test: hints.test.ts guards each folder of guardedDirs] - Make a hint ref with
hintReforbundledRef, and read one withrefTarget(all inhooks/hints.ts). Make the key of a hidden or removed hint withhiddenKey. The typesHintRefandHiddenKeyrefuse a plain string: the full type check finds it inregister.tsx, andtsconfig.pure.jsonin the pure helpers.[test: code.check.mjs fails when a hook outside hints.ts types out the bundled: prefix] - Add or change a tool of this plugin in
TOOLSinhooks/tools.ts: the registration, the full ids (TOOL) and the typed input (parseInput) come from there. In the hooks and the.tstests, writeTOOL.run_code, never the full idmcp__code-mode__run_code.[test: code.check.mjs] - A hook's
.catchwritesnext.errorto the debug log (debugLog) before it answers. A deny that says "see the debug log" must have a line there. Atool.callhook ends with.catch(failClosed): it denies the call when the hook fails. The engine takes only a function literal or a function name there, not a call that makes one. The one exception is theblockDirectMcphook: it applies to every tool, so it fails open. runtime/runner.mjsruns inside the sandbox: Node built-ins only, no dependencies. It needs Node 22.13+, becauseLAUNCHpasses--permission(stable from 22.13; Node 20 knew only--experimental-permission).[test: runner.integration.mjs loads the runner with Node alone, so an import of a package fails]LAUNCH,NO_NETWORKandMKTEMPexist twice: inhooks/register.tsxand intests/runner.integration.mjs.MARKexists inruntime/runner.mjs,hooks/protocol.tsand the same test. Change all copies.[test: runner.integration.mjs fails when a copy differs]- To add a kind of message that the runner sends, add it to
RunnerMessageandRUNNER_FIELDSinhooks/protocol.ts, and give it a case in the message loop ofrun_code. The host drops a message of a kind that is not inRUNNER_FIELDS.[test: runner.integration.mjs fails when the runner sends a kind that is not in RUNNER_FIELDS] - Never weaken a sandbox layer, the guard of hint and function files or the approval of proposals to make a test
pass. Each one is a
safety rule (see
docs/hints.mdxanddocs/how-it-works.mdx). - Make changes to the approval logic (
approval,$.mcp.callpath) in manual mode: the auto mode classifier can refuse them, because they change what auto mode approves.
- Before every commit, do the verification loop in this order. If a step changes code, start again at step 1.
/simplify: the built-in Claude Code skill. It cleans up the diff and applies the fixes. Run it first, so the checks test its edits too./code-review: the built-in Claude Code skill. It reviews the diff for correctness bugs, which/simplifydoes not look for. Check each finding against the code, and fix the real ones.- The checks below. After a change to
hooks/ortests/, also run the type check. /verify: the built-in Claude Code skill. It drives the change end to end and observes the behavior. Run it after a change tohooks/,runtime/orhints/. Skip it when the diff touches only tests or docs: there is nothing to drive. It reads the project recipe in.claude/skills/verify/(SKILL.mdanddrive.mjs): real Claude Code with the plugin and the bench's fake server. If the recipe fails or misses a step, fix it.
- The checks.
[test: CI runs each one]claude plugin test .: the hooks against a fake host (tests/*.test.ts; the shared fakes are intests/fakes.ts). The test kit has no processes.node tests/runner.integration.mjs: the real sandbox under Node.node tests/docs.check.mjs: the doc rules below.node tests/code.check.mjs: the code rules marked[test: code.check.mjs].npx -p typescript tsc -p tsconfig.pure.json: the types of the pure helpers, with no Claude Code types.sh scripts/format.sh --check .: the format of code, JSON and YAML.
node tests/smoke.e2e.mjs: realclaude -pwith the plugin and the bench's fake server. It needs a login and costs API usage, so it is not one of the checks and CI does not run it. Run it after a change tohooks/orruntime/, before a release, and after you raise the pinned Claude Code version. Its checks read the transcript, the fake server's calls and the plugin's files, never the words of the model.- CI (
.github/workflows/test.yml) runs the sandbox test on Linux and on macOS, each with its network block (unshare -rnon Linux,sandbox-execon macOS).EXPECT_NETWORK_BLOCKmakes the test fail where neither works. CI pins the Claude Code version forclaude plugin test ., and a weekly job runs the tests with the newest release. - The full type check (
docs/development.mdx) does not run in CI: its types come from a logged-in Claude Code session. Run it in step 3 of the loop. If.claude-plugin/types/is missing, startclaude --plugin-dir .one time in this worktree (seedocs/troubleshooting.mdx, Limits). - Never put real MCP data, company names, ticket keys, user ids or tokens in tests, hints or docs: this repo is
public. Use
fake,example.atlassian.netand similar.
- When anything under
hooks/,runtime/,hints/or.claude-plugin/plugin.jsonchanges, bumpversionin.claude-plugin/plugin.json: Claude Code caches a plugin per version.[test: CI runs tests/version.check.mjs on each pull request] - Run
claude plugin validate .after a change to a manifest.
The text the model reads is part of the product: the input schemas in TOOLS in hooks/tools.ts,
RUN_DESCRIPTION and SEARCH_DESCRIPTION in hooks/protocol.ts, ADD_HINT_DESCRIPTION, REMOVE_HINT_DESCRIPTION, EDIT_HINT_DESCRIPTION, TRANSFER_TEXT, the transfer blocks and the hint
preamble in hooks/hints.ts, SAVE_FUNCTION_DESCRIPTION, the functions section and the fix note in hooks/functions.ts, the SessionStart text in hooks/session-start.sh, tool results and deny messages, and
the bundled hints in hints/.
- Every sentence must change what the model does. Remove facts the model cannot act on (how approval works for the
person, UI layout, history). The person reads those in
docs/. - Progressive disclosure: put in a description only what the model needs to choose and call the tool. Show the rest
where the model needs it: argument types and hints in the
search_toolsresult, server hints after a failed call, the limit in the message of a cut result. run_codeandsearch_toolsload in every session (isDeferred: false), so each word costs tokens in every session.[test: code-mode.test.ts fails when their registrations grow; raise the limit only for text that changes what the model does]add_hintis deferred: therun_codedescription names it, and that is how the model finds it.remove_hintandedit_hintare deferred too: the hint preamble names them, so the model learns of them when it sees a hint.save_functionis deferred: therun_codedescription names it.[test: code-mode.test.ts fails when no front description or the hint preamble names a deferred tool]- One way to do a thing. The runner also accepts
tools.<server>.<tool>(), but descriptions show onlycall(). - A hint is one short, factual bullet about a server. No data, no instructions about other actions.
User docs are README.md and docs/*.mdx. They are for humans first: a developer who installs the plugin,
writes hints or sets permissions. Out of this set: AGENTS.md, this file and the model-facing text above.
tests/docs.check.mjs checks the rules marked [test].
README.mdstays a short landing page: pitch, quick start, one example, links. User docs live indocs/*.mdx. When behavior changes, change the matching page.- The code is the source of truth. Check every default, limit and behavior in
hooks/orruntime/before you write it. - Lead with what the reader wants to do and a short example. Reference tables come after.
- Keep only facts that change what a user does or understands. Leave out function names unless the user types them, and history.
- Each
docs/*.mdxstarts with front matter (title, one-sentencedescription) and an H1 equal to the title.[test] - Plain Markdown, no JSX, imports or comments, so GitHub renders them. Keep
<…>and{…}inside backticks or code blocks: MDX reads them as JSX.[test] - Relative links use the
.mdxname and the GitHub heading slug. When you rename a heading, fix every link to it.[test: every link and anchor must resolve]
Technical names are allowed: tool names, options, file and product names.
- Instructions: imperative, one instruction per sentence, at most 20 words, condition first ("If X, do Y").
- Descriptions: at most 25 words per sentence
[test], one topic per sentence, at most 6 sentences per paragraph. - Active voice, simple present. "can" for possibility, "must" for a requirement, "do not" for a prohibition.
- No should/may/might/would/could, contractions, semicolons, e.g./i.e./etc., or filler words (just, simply,
easily)
[test]. No -ing forms where a plain verb works. Keep the articles. - Vertical lists for three or more items, numbered lists when order matters. A warning starts with the instruction, then gives the reason.
- One word for one meaning, in all docs:
| Term | Meaning | Do not use |
|---|---|---|
| plugin | code-mode as Claude Code installs it | mod, extension |
| program | The JavaScript that the model gives to run_code |
script, snippet |
| MCP tool | A tool of an MCP server, named mcp__<server>__<tool> |
function, endpoint |
| server | An MCP server. A claude.ai connector is one kind of server. | integration |
| nested call | An MCP call that a program makes | inner call, sub-call |
| sandbox | The Node process that runs one program | VM, container |
| hint | A usage hint: a note about one server, in a hint file | tip, rule, note |
| hint file | A markdown file with hints for one server | hint doc |
| proposal | A hint, a removal, a change or a function that a model tool wrote to pending/, not yet approved |
draft, suggestion |
| band | The area above the prompt that lists proposals | banner, bar |
| allow rule | A permissions.allow entry in Claude Code settings |
whitelist |