Design doc. Historical. Tracks the original decision shape when the daemon was its own
kobedbinary. As of KOB-136 the daemon was merged into the singlekobebinary askobe daemon ..., and the daemon code now lives inpackages/kobe-daemon/; this doc retains the original wording (e.g.kobed start) since it documents the design at the time it was made. For current usage seecli-api.md§6.Original Linear epic: KOB-35.
Today kobe is one Bun process: TUI (Solid + opentui) + Orchestrator +
spawned claude subprocesses + worktree manager. Closing the TUI
(Ctrl+C, accidental terminal close, SSH drop) kills every running
claude subprocess. With 10+ in-flight chats this is brutal — even
with session-resume on disk you have to manually re-prompt every tab
to "continue".
Goal: TUI lifecycle is independent of engine lifecycle. Close the TUI, chats keep streaming. Reopen the TUI, every chat is right where you left it.
Secondary win: faster TUI iteration (hot-reload UI without nuking active sessions), and multi-attach (two terminals, same daemon, synchronised view).
| Decision | |
|---|---|
| Daemon scope | Per-user singleton — one kobed owns every repo's tasks. Not per-repo. |
| Lifecycle | Explicit kobed start / kobed stop / kobed status. No auto-spawn from TUI. Hard-cut: TUI errors out with kobe: no daemon (run \kobed start`)` if the socket is missing. |
| Multi-attach | Yes. N TUIs can attach to one daemon. State (tasks, chat history) is broadcast to all attached clients. UI-local state (cursor, focus, composer draft) stays per-client. |
| Wire protocol | JSON-lines over unix socket. Custom {type, id?, payload} envelope. No LSP, no gRPC. Re-uses the pattern from orchestrator/bridge/server.ts but bidirectional. |
| Attach-time sync | Snapshot + tail. Daemon sends task list + last N (50?) chat messages per task on attach. Older history loads lazily on scroll. No full-history replay. |
flowchart TB
subgraph daemon["kobed (per-user singleton)"]
orch[Orchestrator]
idx[TaskIndexStore]
wt[Worktree manager]
bus[Event bus]
sock["Unix socket\n~/.kobe/daemon.sock"]
orch --- idx
orch --- wt
orch --> bus
bus --> sock
end
subgraph claudes["claude subprocesses (1 per task)"]
c1[claude task A]
c2[claude task B]
cN[claude task N]
end
subgraph tuis["TUI clients (N)"]
tui1["kobe (terminal 1)"]
tui2["kobe (terminal 2)"]
end
orch --> c1
orch --> c2
orch --> cN
sock <--> tui1
sock <--> tui2
Closing tui1 does not touch the daemon, the orchestrator, or any
claude subprocess.
| State | Owner | Why |
|---|---|---|
| Task list, status, archived/pinned flags | daemon | Survives TUI close. |
| Chat history (per task) | daemon (on disk, .kobe/sessions/) |
Same as today — daemon just keeps reading/writing. |
claude subprocess handles |
daemon | The whole point. |
| Worktree paths, git HEADs | daemon | Same as today. |
| Bridge MCP server | daemon | Already a per-process socket; relocate inside kobed. |
| Theme, keybindings, settings | TUI-local (read from disk) | Per-user/per-machine UI prefs, not shared state. |
| Active tab, cursor index, focused pane | TUI-local | Two clients should be able to look at different tasks. |
| Composer draft (typed-but-unsent text) | TUI-local | "What I'm typing" is mine, not shared. Sent message broadcasts. |
| Sidebar scroll position, expand/collapse | TUI-local | View state. |
Litmus test: if I close terminal 1 and open terminal 2, should the state survive? Yes → daemon. No → TUI-local.
Newline-delimited JSON. Each frame:
{ "type": "request" | "response" | "event",
"id": "<uuid>", // request/response correlation
"name": "task.spawn" | "chat.send" | ...,
"payload": { ... } }task.list→{ tasks: Task[] }task.spawn{ repo, title, ... }→{ taskId }task.archive{ taskId, archived }→{}task.rename{ taskId, title }→{}task.delete{ taskId }→{}chat.history{ taskId, before?: messageId, limit }→{ messages }chat.send{ taskId, text }→{ messageId }(tail of stream arrives via events)
task.created{ task }task.updated{ taskId, patch }task.deleted{ taskId }chat.delta{ taskId, messageId, delta }(streaming token chunks)chat.complete{ taskId, messageId }engine.status{ taskId, status: "running" | "offline" | "error" }
Event ordering: monotonically increasing seq per event so a client
that briefly disconnects and reattaches can request "events since
seq=N" — but v1 just resyncs from snapshot on reattach; the seq
infrastructure goes in once a flake actually shows up.
sequenceDiagram
participant TUI
participant Daemon
TUI->>Daemon: connect ~/.kobe/daemon.sock
TUI->>Daemon: request hello { clientId, version }
Daemon-->>TUI: response hello { protocolVersion, daemonPid }
TUI->>Daemon: request task.list
Daemon-->>TUI: response { tasks }
loop per visible task
TUI->>Daemon: request chat.history { taskId, limit: 50 }
Daemon-->>TUI: response { messages }
end
TUI->>Daemon: request subscribe { taskIds: ["all"] }
Daemon-->>TUI: response {}
Note over TUI,Daemon: bidirectional from here on
Daemon-->>TUI: event chat.delta { ... }
TUI->>Daemon: request chat.send { ... }
Subscribe is "all tasks" by default — broadcast cost is small and the TUI may show any task at any time.
Superseded. The original "hard-cut, no auto-spawn, no auto-shutdown" stance below was reversed. The daemon now auto-spawns on first TUI launch and refcounted-lazily self-stops once the last attached GUI disconnects (grace
KOBE_DAEMON_IDLE_GRACE_MS, default 3s). Shutdown never tears down tmux sessions. See AGENTS.md "Daemon lifecycle: refcounted lazy shutdown" for the live behavior.
$ kobed start # binds ~/.kobe/daemon.sock, writes pidfile
$ kobed status # prints pid, uptime, attached clients, task count
$ kobed stop # graceful: tells claude subprocesses to flush, then exits
$ kobed restart # stop + start
$ kobe # opens TUI, attaches to daemon
$ kobe # second terminal, second TUI, same daemonIf kobe runs and the socket is missing:
$ kobe
kobe: no daemon running. start it with:
kobed start
Hard-cut. No auto-spawn. Two reasons:
- Auto-spawn races: two TUIs starting in parallel both try to spawn, one wins, the other ignores its own daemon.
- Clarity:
kobedis a real process the user owns.kobed statusis the answer to "what's happening?". Hidden auto-spawn hides that.
If kobed dies (OOM, panic, kill -9):
- All
claudesubprocesses die (they're children). - TUI's socket connection dies → TUI shows a banner: "daemon offline —
kobed startto resume". - After
kobed start, TUI reconnects automatically. Task list comes back from disk. Each task's status is nowengine_offline. - Pressing
ron an offline task triggers a session resume (already shipped insrc/tui/component/resume-dialog.tsx).
Required for daemon v1: orchestrator must persist task metadata (status, last activity, pinned, archived) to disk on every mutation, not only on graceful shutdown. Chat / session JSONL is already persistent.
Not in v1: auto-resume every task on daemon restart. User-driven
resume per task via r is fine for the first cut.
| Wave | Title | Scope |
|---|---|---|
| D0 | Core extract | Move Orchestrator, TaskIndexStore, worktree manager, bridge server out of TUI imports. Define a KobeCore boundary that is TUI-free — no dependency on opentui or anything that renders. Solid signals stay as an in-process reactive primitive (the TUI happens to consume the same primitive, but the core doesn't depend on rendering). No behavioural change — kobe still runs as one process, but KobeCore is now a self-contained module. |
| D1 | Wire protocol + transport | Implement the JSON-line socket server (server-side push + request/response). Reuse orchestrator/bridge/server.ts shape. Build a typed client (now packages/kobe-daemon/src/client/). Both still in-process for now — TUI talks to a "loopback" client that calls the server via the socket inside the same process. Validates the protocol end-to-end. |
| D2 | kobed binary |
Add kobed entry point (packages/kobe/src/bin/kobed.ts). Pidfile, signal handling, kobed start/stop/status/restart. Default socket: $XDG_RUNTIME_DIR/kobe.sock → fallback ~/.kobe/daemon.sock. TUI now mandatorily talks over the socket; the in-process loopback from D1 is removed. Hard-cut error if no daemon. |
| D3 | Multi-attach broadcast | Track all attached clients in the daemon. Broadcast events to all of them. Add the engine_offline status + reconnect banner to the TUI. Verify: open two terminals, send a message in one, see it stream in both. |
| D4 (deferred) | Resilience polish | Event seq + replay-since-seq, daemon-side per-client backpressure, socket auth token in path, kobed status --json, structured logging to ~/.kobe/logs/. Punt until D3 ships and shows what actually flakes. |
D0 → D3 is the MVP. Each wave is its own KOB issue under the epic.
- Daemon survives
kobeditself dying — no, claude subprocesses die with their parent (Unix). Surviving daemon restart requires PID inheritance tricks (systemd fd-passing or similar) that aren't worth the complexity yet. - Cross-machine attach (TUI on laptop A, daemon on desktop B). Unix socket only. Tailscale/SSH port-forward would work today; native remote attach can come later.
- Permission model.
~/.kobe/daemon.sockis mode0600and that's the auth — single-user assumption. Multi-user shared host is not the target. - TUI hot-reload. Once the daemon split lands, hot-reloading just the
TUI module via
bun --hotbecomes feasible, but it's a separate follow-up — daemon split is the load-bearing prerequisite.
- Where does
kobe mcp-bridgelive? Today it speaks to the orchestrator in-process via the bridge socket. After D2 it should attach tokobedthe same way the TUI does. Question: does the bridge become just another client of the daemon protocol, or does it keep its own socket? Probably the former — one protocol, one socket — but verify that the MCP tools' latency budget tolerates going through the same broadcast bus. - Composer draft persistence. Decision said "TUI-local". But if Jackson types a long message and the TUI crashes, that draft is gone. Open question whether to checkpoint draft to disk per-TUI. Probably not in v1.
- Settings sync. Theme/keybinding files on disk are already
shared (both TUIs read the same
~/.kobe/config.json). What happens if TUI A flips theme and TUI B's already-rendered tree doesn't notice? Probably needs asettings.changedevent from the daemon (or just a file-watcher in each TUI). Defer to D4.