umbel
CLAUDE.md7 starsChanged 5 months agoMITView on GitHub
umbel remote-controls the interactive claude TUI (and similar agent CLIs) over tmux. One TypeScript binary, three faces: Read docs/architecture-v3.md before writing code. It's the canonical multi-CLI design. Positioning & design filter (full thesis: docs/positioning.md). umbel runs one unit of agent work reliably and returns a result the caller can branch on; orchestration belongs to the caller, not umbel. Apply this filter to every change: invest in the noun (the worker), not the verb (the orchestration) — a new capability must…
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- tend-auditSkill
- tend-brainstormSkill
- tend-changeSkill
- tend-discoverSkill
- tend-narrateSkill
- tend-planSkill
- tend-positionSkill
- tend-runSkill
- tendSkill
The file
We split this CLAUDE.md into the rules it gives an agent
9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
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
- Very specific: line 18
Test first: No fix or feature without a failing test that demonstrates the need.
- Very specific: line 91
Wait semantics: mtime snapshot of events/stop before send → watch for mtime advance → done.
- Very specific: line 119
Do NOT use --bare (skips hooks).
- Distinctive: line 149
If you encounter behavior that contradicts the design, STOP and update the architecture doc before working around it.
- Distinctive: line 154
No comments unless WHY is non-obvious.
- Distinctive: line 155
No backwards-compatibility shims.
- Distinctive: line 161
No mocks in e2e tests. Use the fake-claude fixture.
- Distinctive: line 163
No screen-scraping the tmux pane for agent output.
- Very specific: line 164
No bypassing the layer boundaries.
≈ “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
umbel — Project Guidelines for Claude Code
What this is
umbel remote-controls the interactive claude TUI (and similar agent CLIs) over tmux. One TypeScript binary, three faces:
umbel -p [PROMPT] --provider {claude,codex,gemini}— drop-in forclaude -p/codex -p/gemini -p, but routed through the interactive TUI (subscription-billed). Default provider:claude.umbel spawn|send|wait|status|kill(also via MCP) — supervisor verbs for agent-as-supervisor orchestration.spawn --providerpicks the worker; the provider is recorded inmeta.jsonso subsequent verbs auto-route.umbel run workflow.yaml— declarative pipelines with per-workerprovider:.
Read docs/architecture-v3.md before writing code. It's the canonical multi-CLI design.
Positioning & design filter (full thesis: docs/positioning.md). umbel runs one unit of agent work reliably and returns a result the caller can branch on; orchestration belongs to the caller, not umbel. Apply this filter to every change: invest in the noun (the worker), not the verb (the orchestration) — a new capability must be a per-worker primitive on CLI and MCP, composable by the caller, not new workflow syntax; if it can't be that, it probably doesn't belong here. Guardrails must be enforced + external + looped (check → reject + feedback + retry → halt), never advisory. Anchor identity to the neutral worker contract, not the substrate (tmux/subscription) — per-provider adapters absorb the churn; the contract stays stable. Keep the YAML face thin.
Non-negotiable principles
- S.U.P.E.R. — Side effects at the edge, Uncoupled logic, Pure & total functions, Explicit data flow, Replaceable by value. Lower layers know nothing about upper layers.
- Test first. No fix or feature without a failing test that demonstrates the need. Fake binaries (
test/fixtures/fake-{claude,codex,gemini}.sh) drive e2e — never burn real subscription budget in CI. Real-binary smoke tests live intest/smoke/{claude,codex,gemini}/and are gated onUMBEL_SMOKE=1. - No daemon. tmux is the daemon. Filesystem is the state store. Every
umbelinvocation is short-lived. Workers never live on the default tmux socket.adapters/tmux.tsderives a private socket from the state root (UMBEL_TMUX_SOCKEToverrides) and every invocation carries-L. The default socket is shared with the user's own sessions and every other agent, so anything reaping that server — a straytmux kill-server, a user tidying up, another agent's cleanup — takes the whole fleet with it, and does it silently: a vanished session leaves no pane and no log, indistinguishable from a worker that died on its own. That exact bug cost three agents four runs to find. Never add a baretmuxcall; go through the adapter or it lands on the default socket and undoes this. A worker's environment never travels on a command line (umbel#93,docs/worker-env-93.md).new-session -e K=Vput every value on tmux's argv, wherepsshowed it for the server's whole life, and a provider key leaked that way. spawn loads the environment into a tmux buffer from stdin;hooks/launch.shreads it, deletes it, clears what the pane inherited and runs the worker. Every tmux client runs with a minimal environment (tmuxClientEnv), because the server keeps its first client's environment and hands it to every pane. A worker inherits only the allowlist incore/worker-env.tsplus the configuration its provider names ininheritEnv; anything else is passed with--env, a secret by name (--env NAME,{fromEnv}). Never add an argv path for env values, and never widen the allowlist with a name that can hold a secret. A provider names its configuration variables one by one, never a whole vendor prefix:CLAUDE_*also holds the markers a host Claude Code session sets for its children, and an inheritedCLAUDE_CODE_CHILD_SESSIONturned transcript saving off in every claude worker, so no answer could be read. - Files as IPC, JSONL as truth. Hook events are file touches;
chokidaris the event bus. Agent output is read from the provider's transcript file (location captured per-session from the Stop/AfterAgent hook payload), NEVER fromcapture-pane(which is for watching, not parsing). - Throw typed errors, catch at face boundary. No
Result<T,E>library. DiscriminatedErrorsubclasses insrc/core/errors.ts, caught and mapped to exit codes / MCP responses at the faces layer. - Single zod schema per concept. Argv parser, MCP tool schema, and YAML validation all share the same zod definitions. No three-times-defined types.
Architecture layers (strict downward dependency)
faces/ cli | mcp | workflow | -p ← side-effecty user surfaces
operations/ spawn send wait status kill ← composition of adapters
adapters/ tmux fs-state hooks fs-watch jsonl procs ← thin I/O wrappers
core/ types errors wait workflow id ← pure
core/providers/ types claude codex gemini registry ← pure provider abstractionAdapters are injected into operations. Operations are called by faces. Providers are looked up by name from core/providers/registry.ts. Nothing reaches across layers. weeder.toml at the root declares these layers, and weeder's D2 rule refuses a commit that crosses one.
Stack
- TypeScript (strict mode) + Bun runtime + single-binary build via
bun build --compile. - Dependencies:
@modelcontextprotocol/sdk,zod,yaml,chokidar,jsonc-parser. No native modules. - Tmux is the substrate (runtime requirement, not dev).
- Tests via
bun:test. - Lint/format via
biome.
State on disk
~/.umbel/ # default; override via $UMBEL_STATE
├─ sessions/<name>/
│ ├─ meta.json # Session struct (includes provider, providerFiles, repo)
│ └─ events/
│ ├─ stop # touch'd by stop.sh on each end-of-turn
│ ├─ transcript-path # captured from hook payload (jq)
│ ├─ worker-session # the session id bound at startup (bind.sh)
│ └─ log # "<nanosecond timestamp> <event>" lines: bind, turn-start, stop, notify
│ └─ transcript.jsonl # agy only: the worker's stdout, recorded by stream.sh
├─ hooks/stop.sh # global, sessions reference it
├─ hooks/bind.sh # global: records the worker's session id once
├─ hooks/launch.sh # pane wrapper: takes the env buffer, records the exit
├─ hooks/stream.sh # line-protocol wrapper (agy): transcript + stop per turn
└─ workflows/<run-id>/ # workflow run stateFor Gemini, the provider writes <cwd>/.gemini/settings.json into the worker's cwd (absolute path recorded in meta.providerFiles so kill cleans up). Codex instead uses a shared, umbel-managed $CODEX_HOME ($UMBEL_STATE/codex-home) — see Provider-specific surfaces — so nothing is written into the worker's cwd.
A session named foo lives in tmux as umbel-foo. Anonymous sessions get anon-XXXXXX, killed on exit.
The Stop hook (keystone)
Installed once globally at ~/.umbel/hooks/stop.sh. Generic — works for Claude's Stop, Codex's Stop, and Gemini's AfterAgent events because all three include transcript_path in the payload on stdin. It acts only for the worker's own session:
#!/usr/bin/env bash
set -euo pipefail
state="${UMBEL_STATE:?}/sessions/${UMBEL_SESSION_ID:?}"
mkdir -p "$state/events"
payload=$(cat || true)
event_session=$(printf '%s' "$payload" | jq -r '.session_id // empty')
bound_session=$(cat "$state/events/worker-session" 2>/dev/null || true)
if [ -n "$bound_session" ] && [ -n "$event_session" ] && [ "$event_session" != "$bound_session" ]; then
exit 0
fi
if command -v jq >/dev/null 2>&1; then
printf '%s' "$payload" | jq -r '.transcript_path // empty' > "$state/events/transcript-path" 2>/dev/null || true
fi
touch "$state/events/stop"
printf '%s stop\n' "$(date +%s%N)" >> "$state/events/log"Wait semantics: mtime snapshot of events/stop before send → watch for mtime advance → done. Handles "Stop fired before we started watching" and concurrent waiters correctly. The canonical source is STOP_HOOK_SCRIPT in src/adapters/hooks.ts; do not duplicate elsewhere.
A hook event counts only when it comes from the session umbel launched (umbel#118). A worker's environment carries UMBEL_STATE and UMBEL_SESSION_ID, so a CLI it starts inherits them: the global opencode plugin fired and the shared codex hooks were reachable, so a nested CLI's end of turn touched the worker's events/stop mid-turn and wait settled with no transcript-path. Identity is the provider's own session id in the payload (session_id; sessionID in the opencode plugin). Each provider's start event binds it once into events/worker-session through bind.sh (BIND_HOOK_SCRIPT): claude SessionStart at launch, codex SessionStart when the first turn starts (the TUI does not fire it at launch; it still precedes every tool call, verified on 0.154.0), and the first event the opencode plugin sees. stop.sh, notify.sh, and every plugin write act only for the bound id. Once a worker is bound, an event that carries no id is refused too, because it cannot be shown to be the worker's own (umbel#160); with nothing bound an event without an id still fires, and so it does where jq cannot read the payload, so a missing jq never silences a worker. First writer wins: replacing the binding later would hand the worker's identity to whatever ran last. Gemini has no binding yet, because it cannot be run on this account; its hooks stay ungated, which is a known gap. Agy needs none, since its stop comes from its own stdout. Claude's SessionStart runs bind.sh rebind, which replaces the id: a claude the worker starts has no umbel settings, so every claude start event is the worker's own, and /clear gives it a new id. codex and opencode bind first-writer-wins, so a codex or opencode worker that starts a new session of its own (/new) stops reporting stops; respawn it instead.
The stop precedes the handback. Claude fires its Stop hook before it writes the turn's final message: measured on the installed binary, the closing text was missing when the hook fired in 12 of 13 turns and landed 200-400ms later. A read taken at the stop gets the message before the last one, or nothing (umbel#86). So a stop is not "the transcript is final". Each provider says when its transcript closes a turn (turnEnded: claude's last assistant entry is a text block from a message that did not stop for a tool, with no prompt or tool result after it; codex's newest turn marker is task_complete or turn_aborted; opencode's newest exported message has a completed time, did not stop for a tool, has no tool part still running, and carries text). opencode needs the check because its idle also fires when a turn ends with an empty answer, so its stop alone does not promise a handback (umbel#167). readTranscriptAtStop in src/operations/resolve-transcript.ts, the single read point behind read, actions, diff, -p and workflow, polls on it for up to TURN_END_SETTLE_MS after the stop, and waitFor holds reason: 'stop' on the same check, saying in message when the window closed first. Three traps. claude copies the whole message's stop_reason onto every per-block entry, so "the last entry has a stop_reason" proves nothing. A turn answered without a tool has no assistant entry at all when its stop lands, so the newest closing text on disk is the previous turn's; only a user entry after it shows the turn is open. And turnEnded must answer true for a shape it cannot read, or every read stalls for the full window.
Liveness fallback: a worker can die mid-turn (crash / non-zero exit) without ever firing the hook, so events/stop would never advance. waitFor polls tmux has-session and, when the session vanishes with the condition still unmet, returns reason: 'dead' instead of blocking until the timeout (previously a 30-min hang). The real condition is always evaluated before the liveness probe, so a turn that fired stop and then exited still resolves as stop.
Deadlines outlive tmux (umbel#98). waitFor evaluates its deadline inside check(), and check() awaits tmux calls, so a tmux that stops answering used to hold a wait past its timeout. Every tmux client now runs through runTmux in adapters/tmux.ts, bounded at TMUX_CALL_TIMEOUT_MS. The bound is on the wait for its output, not only on the process, because a killed client can leave a child holding the pipe. The wait's deadline also settles on its own timer DEADLINE_GRACE_MS past the deadline, with the last pane seen alive. Never add a tmux spawn outside runTmux, and never put an unbounded await between a deadline and its settle.
A stop is not a promise the worktree is quiet (umbel#106). A turn can end while a command it started, a background Bash call for example, keeps running under the worker's CLI, so a caller that runs a gate at the stop reads a half-written tree. runningCommands in core/procs.ts filters the pane's process tree to commands the CLI started through a shell (<shell> -c, how Claude's Bash tool runs them); the CLI's own children (MCP servers, caffeinate) and the Stop hook itself are not counted. wait reads it once at the stop, and status reads it per entry with one shared ps call, both through adapters/procs.ts injected in Deps. Only the -c form is verified against real claude; another provider whose command runner differs may report none.
Needs-input detection (the inverse keystone): a worker blocked on a prompt (a permission ask, or idle) is alive and has not fired stop, so it would hang to the timeout. A second global hook notify.sh (NOTIFY_HOOK_SCRIPT) touches events/notification on those events; waitFor watches it and settles reason: 'input' with the prompt message, so the caller can send an answer and wait again — the ping. Each provider registers its equivalent, all verified against the installed binary: Claude Notification (permission_prompt + idle_prompt in buildSettingsJson), Codex PermissionRequest (in the global $CODEX_HOME/hooks.json), Gemini Notification/ToolPermission (.gemini/settings.json), OpenCode permission.updated (plugin event — permission.asked is v2-only). The opt-in pane-activity idle net (waitFor's idleTimeoutMs → reason: 'idle') is the universal backstop for a flaky or missing hook (none of the four exposes an idle event). A model request in flight is not stillness: claude writes an api-request entry as it sends and the answer as following assistant entries, so the net holds while one is unanswered, and status reports awaitingProviderSince (umbel#117). events/notification is append-only JSONL (one line per hook fire); core/notification.ts classifies the latest line, so umbel_status exposes needsInput + needsInputReason (permission/idle/question) + pendingTool (and umbel status --json serves non-MCP watchers) — disambiguating a worker blocked on a prompt from one that's merely done-and-idle. waitFor settles reason: 'input' only for awaiting types; informational pings (auth_success, elicitation completion) are ignored. A usage-limit dialog fires the same Notification, so waitFor also reads the provider's limitMatch line from the pane and puts it in message (You've hit your session limit · resets 4:30pm), letting a conductor schedule a resume at the reset instead of retrying (umbel#75). A provider that refuses the turn outright (an exhausted account, say) fires no stop, only that notification; waitFor then reads the provider's errorMatch line from the same screen, so message carries API Error: 402 Insufficient Balance (request_id: …) rather than a prompt the worker is not asking (umbel#129). The limit line wins when both show, since it carries the reset time. A per-worker reliability primitive — orchestration stays with the caller.
Provider-specific surfaces
Each provider lives in src/core/providers/<name>.ts and contributes a buildLaunch, a stopEventName, a parseTranscript, and a supportsUnattended declaration. Per-vendor specifics:
Sign-in (signInMatch, umbel#105). A CLI with no credentials opens on its sign-in screen and waits for a person. Each provider names that screen as a whole-line pattern taken from its installed binary (fixtures in test/fixtures/sign-in/). spawn refuses the worker when the startup loop sees it, and waitFor settles input with inputReason: 'sign-in' when it appears later. A provider may also declare signInCause, a pure reader of the cause its screen shows beside the prompt: gemini opens the same menu when a credential refresh fails, with the failure (quota, validation, a retired client) in a row of that menu (umbel#166), and both the refusal and the wait message carry it, so an authentication failure is not reported as "not signed in" with its cause dropped. Whole-line matters: wait reads the live pane, and a worker's own output can hold the same words in a diff or a reply, never alone on a line. Never press a key on a sign-in screen, since every option starts a sign-in, and never add a startup dialog whose matcher could catch one.
Unattended (--unattended, unattended: true) is the neutral contract term for "no human will be prompted"; each adapter maps it to its own escape (claude permissions.defaultMode=bypassPermissions via --settings, codex --dangerously-bypass-approvals-and-sandbox, gemini --approval-mode yolo --skip-trust, opencode --auto). supportsUnattended is required on the provider contract so a new provider must answer deliberately; spawn refuses at dispatch when it is false, rather than accepting a worker that would wedge on a prompt later. An explicit permissionMode wins over unattended. Note claude's workspace-trust dialog is not covered by any permission flag — it is only skipped in non-interactive mode, and umbel drives a TTY — so the best-effort startupDialogs pane dismissal remains the only defence there.
Claude (claude)
--settings '<inline-json>'carries the hook config (nosettings.local.jsoncollision).- umbel does not pass
--session-id: the CLI picks the JSONL filename and the Stop payload carriestranscript_path.SessionStartregistersbind.sh. --allowedTools "Read,Write,..."scopes permissions without prompts.stopEventName: 'Stop'. Trust dialog is auto-dismissed for real-claudebinaries only.turnStartEvent: 'turn-start': aUserPromptSubmithook (turn-start.sh, registered inbuildSettingsJson) touches it when a submitted prompt begins a turn, sosendproves the prompt landed.submitDelayMs: 750keeps claude from swallowing the submitting Enter during startup (umbel#121).- Do NOT use
--bare(skips hooks). Do NOT use--tmux/--worktree(umbel manages tmux itself). - Custom endpoints (DeepSeek, OpenRouter, local) are reached by the worker's
env(ANTHROPIC_BASE_URL+ANTHROPIC_AUTH_TOKEN+ANTHROPIC_MODEL), not a new provider — same binary, same hooks. Don't add per-endpoint providers; it's an env concern. Recipe indocs/cli-reference.md.
Codex (codex)
- Hooks delivered via a global
$CODEX_HOME/hooks.jsonin an umbel-managed home ($UMBEL_STATE/codex-home), NOT<cwd>/.codex/hooks.json— codex silently ignores project hooks inside linked git worktrees (root cause + proof:docs/codex-worktree-hooks.md). The worker'sCODEX_HOMEis set to that home (reserved launch env — wins over--env);auth.jsonis symlinked from the user's real CODEX_HOME (no secret copy) andconfig.tomlcopied once (carries model/endpoint/MCP, isolated from the user's global trust). Shared across workers, set up idempotently, never written into the user's cwd or cleaned on kill. stopEventName: 'Stop'. Transcript may benullper Codex docs; umbel then finds the rollout itself (below).- Codex writes
<CODEX_HOME>/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonlat the first turn start, before any hook fires. The provider'stranscriptSearchscans that tree and matches the worker cwd in the rollout'ssession_meta, soreadandactionsanswer mid-turn (umbel#68). The match is the resolved path (/private/tmp/x), and it is needed because the sharedCODEX_HOMEholds every worker's rollouts. actionsreadsevent_msg/item_completed:CommandExecution(command, status, exit code),FileChange(per-file add/update/delete, counted asapply_patch) andMcpToolCall(server/tool). Older rollouts useresponse_itemfunction_call/custom_tool_callandevent_msg/patch_apply_end. A script-level failure (a patch that does not verify, a thrown script) writes no item, socustom_tool_call_outputis checked forScript failed,Script error:andapply_patch verification failed. Never re-add the inventedevent_msg/tool_callshape: 0.154.0 does not write it.SessionStartregistersbind.shin the same hooks.json (verified on 0.154.0: its payload carries the samesession_idasStop, and its TUI fires it as the first turn starts), so a codex the worker starts cannot fire the worker's stop.- umbel's startup dialogs trust the global hooks on first use (codex's "Hooks need review" → "Trust all and continue"). Every codex dialog is matched on its highlighted option (
› …), never its title: codex keeps the hooks dialog on screen while it writes the trust, and relative keys sent again there confirmed "Continue without trusting", so no hook loaded and no codex worker stopped (2026-10-22). A change to umbel's hooks.json brings the dialog back for every CODEX_HOME. Its options are numbered when every hook is new and unnumbered when some changed; the patterns accept both. Ready also waits for the newest banner to name its model, since the hooks dialog can open after the prompt line paints on amodel: loadingbanner. - Directory trust is given at launch,
-c 'projects={"<realpath of cwd>"={trust_level="trusted"}}', so a new worktree never shows the trust dialog and nothing is written to config.toml (umbel#112). Trust is keyed on the exact resolved path (/private/tmp/x, not/tmp/x); the dotted formprojects."<path>".trust_levelis ignored by 0.154.0. The trust dialog's second option is "No, quit", which exits 0, so a stray Down there reads as a startup death. That is why the startup loop matches dialogs on the visible screen only: an answered dialog stays in scrollback, and matching it there re-sent the update dialog's Down onto the trust dialog. --permission-mode bypassPermissionsmaps to codex's--dangerously-bypass-approvals-and-sandbox— the unattended equivalent of claude'sbypassPermissions, for conductor-driven workers (e.g. a cross-provider audit) that must run commands with no human present; safety is external (disposable worktree + audit). Any other mode value is rejected for codex.
Agy (agy, the Antigravity CLI, umbel#113)
- The one provider driven over a line protocol, not a TUI: print mode with
--input-format stream-json --output-format stream-json -p=, insidehooks/stream.sh(STREAM_WRAPPER_SCRIPT). The provider declaresstream(encodePrompt,turnEndPrefix). send types the encoded prompt as one line; the wrapper makes the pane's tty non-canonical first, because a canonical tty on macOS cuts a line at 1024 bytes. agy's stdout is the transcript (sessions/<name>/transcript.jsonl), and each{"event":"result"line runsstop.shafter the line is on disk, so a read at the stop is always final. --add-dir <realpath of cwd>is required: without it agy runs its tools in~/.gemini/antigravity-cli/scratch, not the worker's cwd.- Print mode never prompts for a permission. A tool it may not use is denied and listed in the result's
denied_actions; actions reports each as an error. agy's reply to such a turn is often empty, so an attended agy worker'sreadcan be blank. Unattended maps to--dangerously-skip-permissions. - Inherits no env: agy's variables include host-session markers. Sign-in is
Authentication required. Please visit the URL to log in:followed by a paste-the-code prompt; never type into it.
Gemini (gemini)
- Hook config delivered via
<cwd>/.gemini/settings.json. stopEventName: 'AfterAgent'(notStop).matcher: "*", timeout in ms (Codex uses seconds).
OpenCode (opencode)
- Hook delivery: a global JS plugin (
PLUGIN_SOURCE) installed once into opencode's global plugin directory,$XDG_CONFIG_HOME/opencode/plugin/opencode-stop.ts(default~/.config/opencode/plugin/), inert withoutUMBEL_STATE/UMBEL_SESSION_ID. opencode 1.18.18 loads every plugin file there on launch, so one copy serves every umbel state root; umbel adds no entry toopencode.jsoncand removes the per-state-root entries an older umbel registered (…/hooks/opencode-stop.ts). Its first event binds thatsessionIDtoevents/worker-session; later events act only for the bound id, so an opencode the worker started cannot fire the worker's stop (umbel#118). Onsession.statusbusy it touchesevents/turn-start; on idle it writesevents/session-idand touchesevents/stop; onpermission.updatedit appendsevents/notification. The transcript is read viaopencode export <sessionID>; there is no JSONL.session.status idleis the turn end, but it also fires when the turn ends with an empty answer, soturnEndedreads that export: a stop is held until the newest message is complete and carries text (umbel#167). - Launched with
OPENCODE_DISABLE_AUTOUPDATE=1. The autoupdate check opens a modal seconds after launch that holds the keyboard; the first prompt typed at it reached no input box and no turn started, whilesendreported success (umbel#116).turnStartEvent: 'turn-start'makessendwait up to 10 s for the busy signal and exit 1 when no turn begins, so a lost prompt is never reported as sent. readyMatch: /Ask anything\.\.\.|Build · /; an unlisted--modelrefuses the spawn (checked againstopencode models).
Open questions (verify before baking — see docs/architecture-v3.md §14)
If you encounter behavior that contradicts the design, STOP and update the architecture doc before working around it.
Style
- Match surrounding code. Greenfield: ES modules,
.tsextension in imports (Bun resolves),constoverletovervar, narrow types, prefer functions over classes (except for typed Errors). - No comments unless WHY is non-obvious. Identifiers should self-document.
- No backwards-compatibility shims; no half-finished implementations; no TODOs left in committed code.
- Make the SMALLEST reasonable change.
What NOT to do
- No
console.logdebugging in committed code. Use the structured logger (stderr only — never stdout, which is the-presponse channel). - No mocks in e2e tests. Use the fake-claude fixture.
- No
--baremode on workers (skips hooks → breaks umbel). - No screen-scraping the tmux pane for agent output. Use JSONL.
- No bypassing the layer boundaries. Operations don't shell out directly — they go through adapters/tmux.ts.
- No
git reset(per global CLAUDE.md) — usetrashfor safe deletion.
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.

