Katharsis
AGENTS.md5 starsChanged 52 days agoMITView on GitHub
Instructions for AI agents working in OpenScribbler/Katharsis. This file is the source of truth; .claude/CLAUDE.md points here. Everything below is a default, and the person prompting you overrides it. README.md is for people deciding whether to install Katharsis; this file is about how to change it and how to talk to the person who owns it. Katharsis is a Claude Code plugin. It makes the model classify each message the user sends into an exchange type, read the guidance file…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- commitSkill
- prSkill
- review-replySkill
- rules-checkSkill
- setupSkill
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Evidence decides the style: Every ceiling, cue, and shape in a guidance file came out of an A/B run or the ledger.
- Very specific: line 32
The docs describe what the code does: Every claim in README.md and website/ about hook behavior points to something in scripts/ or hooks/ …
- Distinctive: line 40
Use these words when you describe things back to me.
- Distinctive: line 77
Deletions from a steering file are approved before the edit: Before removing or rewording a rule in AGENTS.md, CLAUDE.md, the style, a …
- Distinctive: line 80
Questions from me are read-only: When I ask how something works or whether an approach is sound, answer.
- Distinctive: line 138
Before a commit, run every check whose trigger your change hits.
- Very specific: line 164
Claude Code's mods surface changes between releases: Read .claude-plugin/types/claude-code/index.d.ts, which Claude Code rewrites each time …
- Very specific: line 182
Two sessions, one working tree, is a collision: Use a worktree for parallel work.
- Very specific: line 187
Commit messages and PR bodies follow .github/PULL_REQUEST_TEMPLATE.md: Situation, Target, Proposal.
- Distinctive: line 193
Always put every question, decision, and request for my input on its own line, so it stands out from the prose around it.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.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
AGENTS.md
Instructions for AI agents working in OpenScribbler/Katharsis. This file is the source of truth; .claude/CLAUDE.md
points here. Everything below is a default, and the person prompting you overrides it. README.md is for people
deciding whether to install Katharsis; this file is about how to change it and how to talk to the person who owns it.
What this repo is
Katharsis is a Claude Code plugin. It makes the model classify each message the user sends into an exchange type, read the guidance file for that type, and shape the reply to fit: what opens it, what stays out, and how long it may run. Around that sits a set of hooks that stamp the classification, record every reference code a reply defines into a ledger, and hold a reply once when a few appended lines would repair it. A mod draws the drawer inside Claude Code.
You are almost certainly running under Katharsis while you change it. The output style follows the checked-out
branch, so an edit to output-styles/ shapes your own next reply and a branch switch changes the style in every
session on the machine. The hooks, the drawer, and the guidance files come from the installed plugin, so a change to
them reaches no session until a version bump and reinstall.
What we never compromise on
A change that hurts any of these does not ship, however small.
- Evidence decides the style. Every ceiling, cue, and shape in a guidance file came out of an A/B run or the
ledger. A change to one states in the PR body what was measured, over how many replies, and what moved. Intuition
about what reads better is a hypothesis to test, never a reason to merge.
tests/ab.pyruns the A/B, anddocs/ab-harness.mdwalks through a run. - Guidance over fences. A behavior we want from the model is written as guidance in a style file. A hook holds a reply only when the repair is a few appended lines that leave every line already on screen correct, and no hook ever asks for the reply to be written again. Every hook exits 0 on every path it cannot help on: a malformed payload, a missing reply, an unwritable data directory. A failed hook costs the user a ledger row, never a turn.
- The docs describe what the code does. Every claim in
README.mdandwebsite/about hook behavior points to something inscripts/orhooks/that does it. No hard-coded counts that go stale, and Claude Code's own names for its UI. - The user's data stays theirs. Telemetry records counts and never message text. The ledger and everything
under
~/.claude/katharsis-data/outlive the plugin, and nothing we ship deletes them.
Glossary
Use these words when you describe things back to me.
- You are the agent reading this file and changing Katharsis.
- I, me, and we mean Holden Hewett (
holdenhewett), who maintains Katharsis. - User means a person who installed Katharsis and reads its replies. Your own session has a user too, and it is usually me.
- Reply is a finished assistant message the user reads. Katharsis shapes replies, not tool calls or files.
- Exchange type is one of the classes in the style's cue table, such as
work-requestorapproval. Never "category", "mode", or "intent". - Guidance file is the
styles/<type>.mdfile for one exchange type. The style is the shared body of the two files inoutput-styles/.styles/README.mdholds the rules every guidance file shares. - Cue is a row entry in the classification table that points a message at a type. A split (S1, S2, …) settles a message two types both claim.
- Ceiling is a type's word limit for a reply, counting everything the reader reads.
- Reference code is a coded line such as
F3orAT2. Codes number continuously within a session and stay in the chat; they never appear in a commit, PR, changelog, issue, or file. - Typed turn is a message the user typed. An untyped turn (a task notification, a skill invocation, Stop-hook feedback) inherits the type of the last typed turn.
- Stamp is the record the routing script writes when the model classifies a turn. A gate miss is a typed turn that ended with no stamp.
- Hold is a Stop hook stopping a reply once and asking for the missing lines. Never "block" or "reject" in docs.
- Ledger is
~/.claude/katharsis-data/ledger/: every coded line every reply defined, per project and session. - Drawer is the panel that
/kdraweror the band's open button pulls out to list every coded item, and that you push back in when done. Claude Code's mods API calls that surface a pane, so the code sayspane; in replies and docs, say drawer. The band is the row above the prompt, and the chips are the code buttons under a reply. - Model note is a
styles/models/<family>.mdfile the prompt hook attaches when the model family changes. - kref is the terminal and HTML reader for the ledger (
bin/kref). Using it means a code left the user's context; it is not a log of bad replies.
Who does what
- You draft and publish. You write commit messages, PR bodies, and issue text from the work you did, and post them without showing me first.
- Merging, tagging, and releasing wait for my okay. You can do all three once I say so; until then, prepare the changelog section and stop.
- Follow-up work becomes a GitHub issue in
OpenScribbler/Katharsis, naming the improvement and where you saw it. - Deletions from a steering file are approved before the edit. Before removing or rewording a rule in
AGENTS.md,CLAUDE.md, the style, a guidance file, or a model note, list each cut with the text it removes and get a yes. Additions need no preview, but a new rule still needs its evidence. - Questions from me are read-only. When I ask how something works or whether an approach is sound, answer; do not start editing. A research or planning brief means no file edits.
- Destructive git needs the command named.
reset --hard, force pushes, andbranch -Drun only when the prompt names that command, and that holds for every subagent you brief.
Ways this goes wrong
Each of these has happened on this repo more than once, and each is still possible.
- Docs that sound right and describe nothing. Name a UI element only after you have seen it or found it in
hooks/; a pane or setting you infer from context is an invention. Cut any sentence that would fit any plugin. - Answering from memory. A claim about Claude Code, a model's behavior, or why a rule exists comes from the code, the ledger, or a run on this machine. Say which one.
- Building before measuring. Try the deterministic check first, and add a hook, a pack, or a module only after it falls short. Say what you tried.
- A merged fix is not a live fix. The output styles follow the checked-out branch, but the hooks, the drawer, and
styles/README.mdcome from the installed plugin, which changes only on a version bump and reinstall. Before crediting a fix or blaming a regression, check which code ran: the cache's version in~/.claude/plugins/installed_plugins.json, the~/.claude/katharsissymlink target, and the checked-out branch. - A branch switch changes every session's style. Switching to an older branch rolls back the style in every open session. Do parallel work in a worktree.
What a guidance change must not bring back
These came from rules we have since removed. Check a change to the style or a hook against them before proposing it.
- A mandatory section manufactures its contents. Requiring
## Questionsin every type doubled the questions per reply, and reserved group headings appeared in half of all replies once the style named them. The trigger for any structure is the content, never the reply type. - A hold teaches what its repair asks for. Holding on an ask outside the Questions round taught the model to ask more, so that check now captures and never holds. Hold only on a mechanical defect whose repair adds nothing you would not want repeated.
- Forbidding a behavior in the style does not stop a hook from producing it. Restated open questions rose after the style banned them, because the hook-side repair never shipped. A fix that lives in both places ships in both.
Hit every surface
The most common defect here is a change made in the file you were looking at and missed everywhere else the same behavior lives. Before calling work done, walk this list:
- Tests. A new script arrives with its suite under
tests/, executable, asserting exact outputs and exit codes. - Both output styles.
output-styles/katharsis.mdandkatharsis-coding.mdshare one body, andtests/test-exchange-style.shfails when they differ. - The shared rules. A change to the reference-code table or a rule every type shares lands in both the style and
styles/README.md. - Every guidance file the rule touches, and the type's row in the style's cue table when a cue, ceiling, or split
moves. A new exchange type also touches the routing script's valid set; find every place with
grep -rn 'factual-question' scripts/ hooks/ tests/. - The model notes in
styles/models/, when a change targets one model family's lean. - The docs.
README.mdand the matching page underwebsite/src/content/docs/describe the same behavior and change together. - The demo.
demo/captures/anddemo/media/go stale when the reply shape changes. Say so in the PR rather than leaving stale GIFs unmentioned. - The changelog. Anything an installer sees adds a line under
[Unreleased]inCHANGELOG.md: a guidance file, the style, a hook, a script, a manifest, a documented behavior. Tests, CI, and housekeeping add nothing.
Building and testing
Before a commit, run every check whose trigger your change hits. CI runs the first five on every PR and main
requires them, so a local pass predicts the PR's checks; nothing but you runs the rest.
CI pins Claude Code 2.1.322 until #187 is closed, because 2.1.323's plugin validate --strict type-checks the hooks,
tests, and cli/ and fails on code 2.1.322 accepts. Run npx @anthropic-ai/claude-code@2.1.322 plugin validate --strict .
to match CI, and fix whatever that run reports. An error only 2.1.323 reports is #187's.
| Check | Run it when you change | In CI |
bash tests/run-tests.sh | anything | yes |
shellcheck -S warning scripts/*.sh tests/*.sh | a shell script | yes |
claude plugin validate --strict . | anything | yes |
claude plugin tag --dry-run --force . | plugin.json or marketplace.json | yes |
claude plugin test . | anything under hooks/, or a tests/*.test.ts file | yes |
cd website && bun install && bun run build | anything under website/ | no |
| A live session with the drawer open | anything the drawer draws | no |
python3 tests/ui-check.py | anything the drawer draws | no |
tests/ui-check.py drives this checkout's drawer through every state in its STATES list at 80, 120, and 160
columns, in both themes, over an empty and a long ledger, and saves a PNG of each. It fails on a broken or clipped box,
drawer rows out of column, or error text on screen, and takes about six minutes and one model reply per condition.
Open the images it names, then run python3 tests/ui-check.py review <run-dir> "<what the change should look like>"
for a vision model's verdict on every image. A new interaction adds its state to STATES in the same change.
A few ways to hurt yourself:
- Claude Code's mods surface changes between releases. Read
.claude-plugin/types/claude-code/index.d.ts, which Claude Code rewrites each time it loads this checkout with--plugin-dir, or run it on this machine's build; never answer from memory. - The drawer is not done until you see it. It needs Claude Code 2.1.287 or later and a restarted session. Check it in a live session before saying it works.
- Kill processes by PID.
pkill codex,pkill tmux, orpkill vhshits other sessions on the machine. - An organization-managed account skips some mod events for a plugin the person installed: every
classic.*event,prompt.section,prompt.context,prompt.attachment,prompt.compose,skill.prompt,attribution.text,session.compact, andsettings.read. A hook there never runs on those accounts and lists Katharsis under/pluginErrors.tests/events.test.ts, which CI runs underclaude plugin test ., registershooks/register.tsagainst a stand-in that records every pattern passed toon(), under every combination of the options inplugin.json, and fails on a skipped event,*, a negation, or a glob over a namespace that holds a skipped event, or whenturn.completeis missing.tests/test-plugin-manifest.shfails whenhooks/hooks.jsonnames any module but./register.ts, whenplugin.json's options differ from the ones the test enumerates, or when the test's list of skipped events differs from this one. Use a Stop command hook inhooks/hooks.jsonor a non-classic event instead. - Codex's read-only sandbox cannot run the suites, because
mktempfails there. A delegated review says the tests went unrun or runs with workspace-write. - Two sessions, one working tree, is a collision. Use a worktree for parallel work. A conflict in the
changelog's
[Unreleased]section resolves by keeping both lines.
Git and prose
Commit messages and PR bodies follow .github/PULL_REQUEST_TEMPLATE.md: Situation, Target, Proposal. A commit body
says only what the diff cannot show. The prose in this repo follows the style it ships: the answer first, one term
per concept, complete sentences.
Questions
Always put every question, decision, and request for my input on its own line, so it stands out from the prose around it; never bury one in a paragraph. Ask in prose, one decision per question, with the options and a recommendation inside the question. Ask only for a call that is mine: expensive to undo or reaching past this machine, and not inferable from what I said, the repo, or this file. Everything else, decide and say so in a clause.
How we work
- Try the smallest change that could work, and a deterministic script before an LLM step. Justify a new file or section in one line.
- Disagree plainly, with evidence, and correct me when I am wrong.
- Say "I think" when unsure, and never state a guess in the register of a fact.
- Implement what was asked. No extra configurability, abstractions, or fallbacks.
- You always have permission to verify a claim, run the check, or finish the thought, including when my message is a question. Do it rather than asking, caveating, or listing it as a next action.
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.

