umbel: Instructions file for Claude Code

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 for claude -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 --provider picks the worker; the provider is recorded in meta.json so subsequent verbs auto-route.
• umbel run workflow.yaml — declarative pipelines with per-worker provider:.

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

1. 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.
2. 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 in test/smoke/{claude,codex,gemini}/ and are gated on UMBEL_SMOKE=1.
3. No daemon. tmux is the daemon. Filesystem is the state store. Every umbel invocation is short-lived. Workers never live on the default tmux socket. adapters/tmux.ts derives a private socket from the state root (UMBEL_TMUX_SOCKET overrides) 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 stray tmux 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 bare tmux call; 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=V put every value on tmux's argv, where ps showed 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.sh reads 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 in core/worker-env.ts plus the configuration its provider names in inheritEnv; 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 inherited CLAUDE_CODE_CHILD_SESSION turned transcript saving off in every claude worker, so no answer could be read.
4. Files as IPC, JSONL as truth. Hook events are file touches; chokidar is the event bus. Agent output is read from the provider's transcript file (location captured per-session from the Stop/AfterAgent hook payload), NEVER from capture-pane (which is for watching, not parsing).
5. Throw typed errors, catch at face boundary. No Result<T,E> library. Discriminated Error subclasses in src/core/errors.ts, caught and mapped to exit codes / MCP responses at the faces layer.
6. Single zod schema per concept. Argv parser, MCP tool schema, and YAML validation all share the same zod definitions. No three-times-defined types.