Architecture

Cathead Coding is a terminal product layer over DeepSeek Harness (DSH). It uses public DSH packages and a clean-room interaction design; it does not copy implementation code from proprietary coding CLIs.

Process boundary

The CLI process owns rendering, keyboard input, command parsing, and a SessionController. A private child process boots the Cordis composition in config/cordis.yml and exposes the DSH Host ApiProxy through the small, versioned cathead.bridge/1 NDJSON protocol. Runtime stdout is reserved for protocol frames; diagnostics use stderr.

The bridge is deliberately private. Users and scripts consume cathead run --output jsonl, whose event format is independent of DSH transport details.

Session lifecycle

1. The controller starts one runtime and subscribes to host and multiplexed session events.
2. It creates a session, resumes an exact id, or selects the newest non-blank session for the current workspace.
3. Prompts are sent to the same session. Prompts submitted while busy remain visible in DSH's authoritative queue.
4. Assistant chunks, final messages, tool calls/results, projections, and interaction requests are folded into an external store consumed by Ink. Markdown is parsed only for presentation; the durable transcript remains unchanged.
5. An idle event only ends a turn. The UI and runtime remain alive until /exit, Ctrl-D, or the confirmed idle Ctrl-C gesture.
6. Shutdown unsubscribes, pauses an active auto goal, asks the runtime to stop, and terminates a child that does not exit within the grace period.

Durable transcript messages are kept separate from ephemeral streaming text and tool progress. Sequence numbers deduplicate replayed history and live events. The viewport independently selects the newest messages that fit, so rendering constraints never mutate session history.

Plan, Todo, goal, token pressure, token usage, queue, job, subagent, and Git state are independent projections. A noisy stream update therefore does not need to rewrite transcript history. Model and subagent catalogs are best-effort capabilities so an older custom bridge cannot take down the core conversation.

Session search uses a derived SQLite FTS index under ~/.cathead. The JSONL session log remains the source of truth; the index can be recreated and is not a second remote persistence service.

Slash commands are dispatched by the private runtime bridge through DSH's command registry before ordinary prompts reach Host ApiProxy. This keeps /plan and /compact deterministic on DSH rc.6, whose public prompt response schema includes commands but whose current prompt implementation does not dispatch them.

Control semantics

• queue schedules a new turn after current work.
• steer injects guidance at the next tool boundary.
• cancel aborts the active turn while retaining the session and queued work.
• goals continue across ordinary idle boundaries, but Cathead creates them with a 16-round cap and adds a separate 30-minute timer. Renewal is explicit.
• approval and question requests pause the UI for a response. Non-interactive mode refuses them rather than guessing.
• plan review uses the same answerable question channel, carrying a Markdown plan and explicit approve/revise choices.
• background Bash jobs and subagents remain visible and independently controllable while the parent turn continues.

Security boundary

The default sandbox policy is workspace-write, rooted at the user-selected --cwd. Broader operations flow through the approval provider. Credentials enter only through environment variables. Session and storage roots live under ~/.cathead unless explicitly overridden.

The runtime composition is replaceable. A deployment can change providers or policies in Cordis without coupling those choices to the terminal reducer or public automation output.