aesop / stdio
CLAUDE.md2 starsChanged 31 days agoMITView on GitHub
Purpose: a Claude-Code-shaped generic filter. Anything piped on stdin is accepted and passes through byte-exact by default. Callers select a format when they need one (text, JSON lines, stream-json, or the frame grammar below). The TTY detection seam (stdio/tty.mjs) is used by chat/ (the interactive chat); pipes stay clean. Node stdlib only, ESM .mjs. Node was chosen because bin/cli.js and mcp/server.mjs are already Node, and Node gives uniform binary stdio on Windows and Linux. Files - stdio/cli.mjs — entrypoint; parses…
In this repository21 other files it gives its agents.
- auth/CLAUDE.mdCLAUDE.md
- bin/CLAUDE.mdCLAUDE.md
- chat/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- daemons/CLAUDE.mdCLAUDE.md
- dash/CLAUDE.mdCLAUDE.md
- driver/CLAUDE.mdCLAUDE.md
- hooks/CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- monitor/CLAUDE.mdCLAUDE.md
- scan/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- state_store/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- tools/CLAUDE.mdCLAUDE.md
- ui/CLAUDE.mdCLAUDE.md
- buildsystemSkill
- dashboardSkill
- fleetSkill
- healthcheckSkill
- powerSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 44
Every error envelope carries a machine-readable code (R-CONTROL-1).
- Very specific: line 55
Default raw mode never parses or alters bytes.
- Distinctive: line 56
Never buffer the whole input.
- Distinctive: line 60
No escape sequences on a non-TTY stdout.
≈ “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
stdio/ — Generic stdin/stdout pipeline
Purpose: a Claude-Code-shaped generic filter. Anything piped on stdin is accepted and passes through byte-exact by default. Callers select a format when they need one (text, JSON lines, stream-json, or the frame grammar below). The TTY detection seam (stdio/tty.mjs) is used by chat/ (the interactive chat); pipes stay clean.
Universal rules (every domain)
- Feature branch only, never main; every push gated by
python tools/secret_scan.py --stagedexit 0. - Tests never pollute cwd or global git config; temp dirs only.
- In worktrees use ABSOLUTE paths under the worktree for every write.
- Domain docs stay minimal-but-complete; update this file in the same PR as the code it describes.
Runtime
Node stdlib only, ESM .mjs. Node was chosen because bin/cli.js and mcp/server.mjs are already Node, and Node gives uniform binary stdio on Windows and Linux.
Contract
Files
stdio/cli.mjs— entrypoint; parses flags and calls the pipe core.stdio/pipe.mjs— corerunPipe({stdin, stdout, stderr, argv})returningPromise<exit code>. The chat's default backendpipeSource(line, {stdin?})inchat/session.mjsdrives this core in raw passthrough and streams each stdout write as it arrives (it accepts an injectedstdin); this file's contract is unchanged.stdio/frames.mjs— frame encoder and decoder.stdio/tty.mjs—isTTYanddetectMode; the seam for the interactive chat.stdio/tty-decision.js— CommonJS home ofisTTYanddetectMode(stream.isTTY === true);tty.mjsre-exports it,bin/cli.jsrequires it directly.
Flags
--input-format raw|text|stream-json|frames(defaultraw)--output-format raw|text|json|stream-json|frames(defaultraw)--content-type <mime>— content type declared for raw payloads--max-frame <bytes>— upper bound on one frame payload
Frame grammar
AESOP-PIPE/1\n
F <channel> <content-type> <length>\n<payload>\n
E <exit>\n- Channels:
dataandcontrol. - Control message types:
hello,meta,event,receipt,seal,error,done. Anerrorcontrol frame exits 2 with the fixed lineupstream reported an error; its message is never echoed. - An unknown control message type marked critical fails closed (exit 2). An unknown non-critical type is skipped.
stream-json records
datarecords carry the payload base64-encoded.resultrecords carrybytesandsha256of the full payload.controlrecords (op dispatch) are accepted only with--input-format stream-json --output-format stream-json. Each record{"type":"control","op":"<op>","id":<string|number|null>}gets one stdout reply line{"type":"control","op":...,"id":...,"ok":true,"result":{...}}; a control-only stream prints just its replies. Ops come from a registry injected bysetControlDispatcher(auth/cli.mjs, preloaded by bin/cli.js via--import); without a registration the pipe exits 2 with oneaesop-pipe:line. A refused op does not stop the pipe: it gets an ok:false reply and the pipe exits 0. An unknown op gets{"type":"control","id":<id>,"ok":false,"error":"unknown op","code":"unknown_op"}with noopfield; a known op with a rejected argument keepsopand a fixed safeerror(for exampleunknown model selector).- Every error envelope carries a machine-readable
code(R-CONTROL-1). The code set is owned by auth/cli.mjsCONTROL_ERROR_CODES; a refusal with no code is reported asop_failed. - Malformed framing (a non-JSON line, or a control record with no
id) is a FramingError: exit 2, exactly one stderr line with theaesop-pipe:prefix, and no stdout record.
- Every error envelope carries a machine-readable
- No caller-supplied string (flag, op, selector, provider, label, record type, a
resultrecord's bytes value) is echoed on stdout or stderr;unknown flag,unknown optionandunexpected argumentlines carry no value.--controlor--control=<x>on any verb or entry path, the pipe included, exits 2 with the bareCONTROL_CHANNEL_MESSAGEline (noaesop-pipe:orerror:prefix). The line and the one predicatehasControlFlagare defined once in stdio/pipe.mjs and re-exported by auth/cli.mjs (the pipe never imports auth/).
Exit codes
0— ok.2— usage error, or malformed input the caller explicitly declared.- EPIPE on stdout exits
0.
Invariants
- Default
rawmode never parses or alters bytes. - Never buffer the whole input. Backpressure is respected: pause reads while the output is full.
- Stdout carries payload only. Stderr carries one-line
aesop-pipe: <reason>diagnostics only. - Fail closed only on malformed input the caller explicitly declared a format for.
- Zero dependencies, enforced by
tests/stdio-zero-dependency.test.mjs. - No escape sequences on a non-TTY stdout.
- Aesop-specific content (receipts, events) is only a control message type. Nothing aesop-specific is required to use the pipeline.
How to test
node --test tests/stdio-pipe.test.mjs tests/stdio-zero-dependency.test.mjs tests/stdio-cli-wiring.test.mjsAnti-vacuity: a test is only accepted when breaking the production code in stdio/ turns it red.
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.

