Codename. Read alongside
../HANDOFF.mdand../CLAUDE.md. This document is the design philosophy + architecture sketch. It is opinionated. Things marked OPEN are decisions the user (Jackson) needs to make before we code.Current-shape note (v0.6+, 2026-06). kobe is now tmux-native: it launches interactive engine CLIs inside per-Task tmux Sessions and enters them by Handover. Older sections that discuss a live
AIEngine.spawn/streamchat renderer describe the v0.5 design lineage, not the current implementation. For current vocabulary and file ownership, read../CONTEXT.mdandARCHITECTURE.md.
A TUI that gives one developer the ergonomics of running many parallel AI coding tasks at once, with local interactive engine CLIs such as Claude Code and Codex running inside tmux.
Conductor (conductor.build) is the visual reference. We want its layout grammar — task rail, workspace context, file/diff tooling, terminal-native execution — but in a terminal, opinionated about local-first workflows, and conservative about pluggability.
This is not a Conductor clone. It is a TUI that takes Conductor's layout grammar as a starting point and re-derives every other choice from "what does a Claude-Code-native, terminal-first orchestrator actually want to be?"
Five principles. In tension by design — when they conflict, the earlier one wins.
If a module already exists in refs/ and works, we copy it. We don't reimplement scrollboxes, dialog systems, theme engines, JSONL readers, or stream-json parsers.
The job of this project is the orchestration layer, not the primitives beneath it. opencode has spent years polishing the TUI shell. opcode has spent months polishing the Claude Code subprocess loop. We are not smarter than that.
The corollary: we accept the constraints those modules impose. If opencode's dialog stack works a certain way, we live with that way. We don't fork to "improve" it on day one.
We don't build a vendor-neutral LLM abstraction. We don't ship @ai-sdk/* adapters. kobe runs local interactive engine CLIs and lets those tools own auth, prompts, approvals, and model execution.
But: we keep engine-owned Adapter seams for product identity, command launch, hook normalization, history, telemetry, and model/catalog capability. Neutral layers ask those Adapters instead of hard-coding Claude/Codex strings.
Pluggability is at one layer, not every layer. Specifically: the boundary between Task and the local interactive engine running inside that task's tmux Session. Everything else (theme, panes, persistence) is hardcoded for now.
Conductor is a desktop Electron app. We are not. That asymmetry has to mean something — otherwise we're just a worse Conductor.
What the terminal buys us:
- Lives where developers already are (tmux, ssh, VPS, server boxes).
- Composable with shell pipelines,
gh,git,jq. - One keystroke instead of one click.
- Free remote access (you already SSH'd in).
What we give up: visual richness, drag-drop, instant rendering of large diffs, native browser embeds. We don't fight those. If a feature is fundamentally graphical (e.g. screenshot diff of a deployed page), we shell out, we don't fake it.
The unit of work is a Task. A Task is a triple:
Task = (git worktree, tmux Session, branch)
All three are 1:1 with the Task. The tmux Session may contain multiple ChatTabs (tmux windows), but it is still owned by one Task. Killing a task removes the worktree (after confirmation), kills the task's tmux Session, and leaves the branch in place. This invariant simplifies a lot of UI.
We don't build a session DB. Engine CLIs already persist transcripts (~/.claude/projects/..., ~/.codex/sessions/...). kobe reads those through engine-owned history/usage Adapters.
We do keep a small task index — title, repo, branch, worktree path, status, vendor/model/settings, ordering, timestamps — because the engine CLIs don't know about "tasks". But this index is a manifest, not a database. Single JSON file at first, SQLite if we hit pain.
When in doubt, the source of truth is on disk in a place that already exists.
This is the one place where "delegate to Claude Code" is most tempting to ignore — the chat is interactive and live. Resist. The minimal-state pattern (cribbed from opcode's claude-code-session):
- One source-of-truth array for chat messages, hydrated from
engine.readHistory(sessionId)on session mount, then appended-to as liveEngineEvents arrive. No separate "inflight" buffer. No re-read ondone— the stream events ARE what just got written to JSONL. - No per-session message cache. On session switch, clear the array, re-read from disk for the new session. Reload is cheap (JSONL is local), bookkeeping a per-session cache is not.
isStreamingis derived from events, never manually toggled.truebetween user submit anddone/error. The loading indicator and the streaming cursor both key off this single flag.- Tool call correlation happens at render time, by searching the messages array backward for a matching
tool_use_id. Do NOT maintain aMap<id, ToolStart>alongside the message list — that's the kind of duplicated state that drifts. - Title generation: opcode uses
Session ${id.slice(0,8)}(no derived title). kobe goes lighter on UX —title = first 40 chars of first user prompt, "…"-truncated— derived inOrchestrator.createTask. Phase 2 polish may add an LLM-summary side-call.
The shape impedance — engine.readHistory() returns Message (per-message disk shape), engine.stream() yields EngineEvent (normalized live deltas) — is real and not papered over. The chat keeps both as backing data and renders them with a single row mapper. Don't synthesize fake Message entries from events; honest type separation beats brittle round-tripping.
The principle, in one line: anything that can be re-derived from Claude Code's JSONL is not state we own.
| kobe is | kobe is not |
|---|---|
| A TUI orchestrator for Claude Code | A Claude Code replacement |
| A Conductor-shaped layout in the terminal | A Conductor port |
| Opinionated about the engine (Claude Code) | Vendor-neutral / model-agnostic |
| Pluggable at the engine layer | Pluggable at every layer |
| Greenfield, building on opencode shell | A fork of opencode |
| Single-developer-focused | Team collaboration software |
| Local-first | Cloud-hosted |
Claude-Code-era multi-task orchestration is a small, fast-moving space. Roughly:
| Product | Form | Multi-task | Engine | Notes |
|---|---|---|---|---|
| Conductor (conductor.build) | Desktop (Electron) | Yes | Claude Code | Our visual reference |
| Crystal (stravu/crystal) | Desktop | Yes | Claude Code | Closest spiritual sibling; multi-session manager |
| Claude Squad (smtg-ai/claude-squad) | TUI | Yes | Claude Code / Codex / Aider | Closest terminal analog. Worth a look. |
| vibe-kanban (BloopAI/vibe-kanban) | Web + Tauri | Yes | 10+ agents | Sunsetting — but their crates/executors/ is the cleanest agent-abstraction reference we have. Cloned to refs/. |
| opcode (winfunc/opcode) | Desktop (Tauri) | Partial | Claude Code | Our plumbing reference |
| opencode (sst/opencode) | TUI | No (single session) | Multi-vendor | Our shell reference |
| Plandex | CLI/TUI | Partial (plans) | Multi-vendor | Plan-mode workflow |
| Aider | TUI | No | Multi-vendor | Single chat |
| Goose (Block) | Desktop | Partial | Multi-vendor | Recipe + sessions |
The interesting whitespace for kobe:
- TUI + multi-task + Claude-Code-opinionated is a thin slice. Claude Squad is in it. Conductor isn't (desktop). Crystal isn't (desktop). opencode isn't (single-session).
- The only direct competitor in this slice is Claude Squad. It uses tmux + git worktrees, similar architecture. We should read it before we ship — not to copy, but to know where it falls short.
Action item: skim smtg-ai/claude-squad README + architecture before MVP. Add as a fourth ref if useful.
┌─────────────────────────────────────────────────────┐
│ TUI Shell (opentui + Solid, copied from opencode) │
│ ├ panes: history, preview, tree, terminal, chat │
│ ├ dialogs, command palette, theme │
│ └ keybindings, focus mgmt │
├─────────────────────────────────────────────────────┤
│ Orchestrator (kobe core, our code) │
│ ├ Task lifecycle (create / run / pause / archive) │
│ ├ Worktree manager (git worktree wrapper) │
│ ├ Status grouping & sidebar tree │
│ ├ Task index (JSON manifest) │
│ └ Background workers (status polling, log drain) │
├─────────────────────────────────────────────────────┤
│ AI Engine Port (interface — single seam) │
│ spawn(cwd, prompt, opts) → SessionHandle │
│ resume(session_id) → SessionHandle │
│ stream(handle) → AsyncIterable<Event> │
│ readJsonl(session_id) → Message[] │
├─────────────────────────────────────────────────────┤
│ Engine impl (Claude Code subprocess, ported │
│ from opcode) │
└─────────────────────────────────────────────────────┘
The AI Engine Port is the only declared interface. Above it: orchestrator owns task semantics. Below it: a Claude Code subprocess wrapper (see §6).
interface AIEngine {
// Start a fresh session in a working directory.
spawn(cwd: string, prompt: string, opts?: SpawnOpts): Promise<SessionHandle>;
// Resume an existing session by id (Claude Code's session uuid).
resume(sessionId: string, prompt: string): Promise<SessionHandle>;
// Stream events from a live session (stream-json line per event).
stream(handle: SessionHandle): AsyncIterable<EngineEvent>;
// Read historical messages from disk (JSONL on Claude Code).
readHistory(sessionId: string): Promise<Message[]>;
// Stop a running session (SIGTERM → SIGKILL with grace).
stop(handle: SessionHandle): Promise<void>;
}
type EngineEvent =
| { type: "assistant.delta"; text: string }
| { type: "tool.start"; name: string; input: unknown }
| { type: "tool.result"; name: string; output: unknown }
| { type: "usage"; input_tokens: number; output_tokens: number }
| { type: "done" }
| { type: "error"; message: string };The events are normalized — we don't leak Claude Code's stream-json shape into the orchestrator. This is the only place we pay an abstraction tax. It's worth it because it's the only place that ever gets swapped.
- Task index (
~/.kobe/tasks.json): array of{id, title, repo, branch, worktreePath, sessionId, status, createdAt, updatedAt}. Single file, write-on-mutation. SQLite migration path if it ever gets slow. - Worktree manager:
git worktree add/remove, mapped to task lifecycle. Aware of dirty state. - Status state machine:
backlog → in_progress → in_review → done(pluscanceled,error). Driven by orchestrator events, not by polling pane content. - Background workers: one per running task, draining the engine's stream into the sync store.
- Sidebar tree: groups tasks by status (matching Conductor's grouping); optionally by repo at a higher level when many repos are open.
The orchestrator stays TUI-free: no imports from @opentui/* or anything that renders. Solid signals are allowed as an in-process reactive primitive (the TUI subscribes to the same signals), but the daemon must be runnable headless. This is the seam Wave D0 of the daemon split formalises — see design/daemon.md §9.
Everything under src/tui/** runs inside a render process — the TUI itself or a tmux pane host. A synchronous subprocess there (spawnSync & friends) blocks the whole event loop for the child's lifetime, and git commands are O(repo size): a spawnSync git status on the sidebar's ~2s tick hard-froze the Tasks pane the moment a 30GB repo's row rendered. So the rule is absolute, not advisory:
- Recurring data (branch hints, dirty counts — anything read from a memo on a tick) goes through
src/tui/lib/background-poll.ts:read(key)is a cheap reactive signal read,poll(key)is fire-and-forget with in-flight dedupe, adaptive cadence, and timeout + hard backoff. Failures keep the last value — panes go stale, never freeze or error. - One-shot actions (e.g. building the Create-PR prompt) use async spawn (
spawnCapture) with plainawaitat the call site — no poller needed, but still neverspawnSync.
The rule is enforced by packages/kobe/test/tui/render-path-sync-guard.test.ts, which scans src/tui/** for sync-subprocess imports/calls and fails on anything outside its short, reason-annotated whitelist (post-renderer.destroy() updater paths and the one-shot CLI helper). Extend the whitelist only with a reason — and prefer not to.
Pane hosts live for days, so per-tick allocation that LOOKS like garbage can be a leak in disguise. The concrete failure (2026-06): the Ops pane's fs-watch refresh rebuilt the file tree with all-new row objects every event; Solid's <For> keys by object identity, so every refresh destroyed and recreated every row's renderables — and @opentui/core 0.2.4 retains a small amount of native memory (~300B) per renderable create/destroy cycle. A busy worktree refreshes thousands of times a day → two production Ops panes at 2.9GB / 1.7GB RSS while the Tasks pane (stable row objects) sat at ~100MB.
So for any list a pane rebuilds on a poll/watch tick:
- Suppress no-op refreshes at the signal — give the source signal a content-
equalsso an event that produced identical data notifies nobody (filetree/rows.tssameFileList/sameStatusEntries). - Reconcile identity on real changes — keep the PREVIOUS row object whenever its fields are unchanged so
<For>reuses renderables (reconcileRows); return the previous ARRAY when nothing changed at all. - Pin the contract with
toBe— identity reuse is invisible to value-equality assertions; a regression renders identically while the leak quietly returns (test/tui/filetree-rows.test.ts).
The Tasks pane never needed this because its rows derive from stable Task objects — which is the cheapest way to comply: derive rows from stable upstream identities when you can, reconcile when you can't.
The AI engine port is the single pluggability seam.
Subprocess wrapper around the claude CLI. Algorithm ported from opcode (refs/opcode/src-tauri/src/commands/claude.rs):
- spawn
claude -p <prompt> --model <model> --output-format stream-json --verbose - BufReader → JSONL parse → typed events (this is the normalization layer)
- on session init message, capture session_id; stash in task index
- multi-session =
Map<TaskId, SessionHandle>in memory - stop = SIGTERM with 5s grace, then SIGKILL
Reuses Claude Code's auth. We assume claude is on PATH and authed. We do not handle login.
Earlier drafts of this doc carved out a Conductor-backed v0.5 engine implementation for "kanban mode on top of Conductor." We've dropped it: kobe's value is the UI and local engine CLIs work. Re-litigate only if a concrete swap need surfaces; at that point extend the current Adapter-owned command/history/hook seams instead of reviving the v0.5 stream interface.
Concrete inventory from the three explore agents.
| Module | Path | Usage in kobe |
|---|---|---|
| Dialog system | packages/opencode/src/cli/cmd/tui/ui/dialog.tsx |
All modal flows (new task, confirm delete, etc.) |
| Diff dialog | packages/opencode/src/cli/cmd/tui/component/dialog-diff.tsx |
File preview pane base (the user already wrote this) |
| Sidebar | packages/opencode/src/cli/cmd/tui/routes/session/sidebar.tsx |
History pane (status-grouped tasks) |
| Layout primitives | packages/opencode/src/cli/cmd/tui/component/border.tsx + opentui core |
All pane composition |
| Theme system | context/theme.tsx + context/theme/*.json |
Colors, plug-and-play |
| Command palette | context/command-palette.tsx |
cmd-k task switcher |
| Slash commands | pattern from app.tsx appCommands |
/new, /diff, /run, etc. |
| Sync store | context/sync.tsx |
Reactive state for messages/tasks |
| KV store | context/kv.tsx |
Persisted UI state (cursor, expanded groups) |
Strategy: lift packages/opencode/src/cli/cmd/tui/ into our repo as a starting point, then strip what we don't need (auth, vendor adapters, opencode-specific routes). What's left is ~70% of our shell, free.
| Module | Path | Usage in kobe |
|---|---|---|
| Subprocess spawn | src-tauri/src/commands/claude.rs lines 919–1014 |
ClaudeCodeLocal.spawn/resume/stop |
| stream-json parser | src-tauri/src/commands/claude.rs lines 1173–1327 |
stream() event normalization |
| JSONL reader | src-tauri/src/commands/claude.rs lines 147–230 |
readHistory() |
| Session registry | src-tauri/src/process/registry.rs |
In-memory Map<TaskId, Handle> |
| Binary discovery | src-tauri/src/claude_binary.rs |
Find claude on PATH/NVM/Homebrew |
Strategy: rewrite in TS (~400 LoC total). Algorithm is straightforward; Rust→TS is a clean translation. No async runtime gymnastics — Node streams + child_process are enough.
vibe-kanban is sunsetting; the repo is a free archive of an agent-orchestration system that already shipped. Two crates are directly relevant:
| Crate | Path | Why |
|---|---|---|
executors |
refs/vibe-kanban/crates/executors/ |
Common interface across 10+ agents (Claude Code, Codex, Gemini, Amp, Cursor, etc.). Read this before finalizing our AIEngine port — it's the most battle-tested shape we have. |
worktree-manager |
refs/vibe-kanban/crates/worktree-manager/ |
Worktree creation/cleanup tied to task lifecycle. Algorithm port to TS; we don't take their multi-agent assumption. |
workspace-manager |
refs/vibe-kanban/crates/workspace-manager/ |
Workspace = (worktree + agent + branch) bundling. Same triple as our Task. Read for invariants. |
services |
refs/vibe-kanban/crates/services/ |
Background dispatch + lifecycle services. Architecture reference. |
Strategy: read for interface shape and invariants, port nothing. Their stack is Rust + multi-agent + web; we are TS + Claude-Code-only + TUI. The lessons are at the boundary, not the implementation.
Note: vibe-kanban supports many agents because it has to. We support one because we choose to. If our AIEngine port shape ends up looking like a stripped-down version of their executor interface, that's a sign we got the shape right.
| Pattern | Why we want it |
|---|---|
| Background worker pool with channel-driven log drain | Multi-task concurrency without blocking the UI thread |
| Round-robin status polling | If we ever poll pane content, do it batched |
| Group tree + flatten + status filter | The sidebar grouping primitive (Done/In progress/Backlog) |
| SQLite + WAL persistence | Migration target when JSON manifest hits pain |
| Configurable hotkey lookup table | Remappable keys from day one |
Strategy: read for concepts, port nothing directly. agent-deck is Go and observer-shaped; kobe is TS and orchestrator-shaped. We borrow the architecture, not the code.
Locked: TypeScript + @opentui/core + @opentui/solid + Solid.js + Bun (matches opencode).
Rationale: §7.1 alone justifies it — 70% of the TUI shell is reusable from opencode. The user has already written Solid+opentui code for this domain (dialog-diff.tsx). Subprocess management is fine in Node, JSONL parsing is trivial.
Rejected paths:
- Go + Bubble Tea: agent-deck-style. Loses the §7.1 reuse. Cleaner subprocess story but not where the bulk of work lives.
- Rust + Ratatui: maximum perf for zero benefit at this scope.
- Split front/back (Go TUI + TS backend): more complexity, not less — adds IPC seam between two processes that should be one.
Decision is locked; do not re-open.
The user has declared Phase 1 = all five panes (per Conductor screenshot). That said, we ship the panes in an order that lets every step be a working product:
- Single task, chat-only — wire up
ClaudeCodeLocal, render one session in a single chat pane, type prompt, stream response. End-of-step: I can converse with Claude Code through kobe. - Add history sidebar — task list (one task), status badge, cursor nav. End: I can see the task in the sidebar; same chat.
- Add multi-task —
/new taskcreates a worktree + branch + session. Switch tasks via sidebar. End: I have N concurrent tasks in N worktrees. - Add file tree pane — list files in active task's worktree, distinguish changed files. End: I can browse files for a task without leaving the TUI.
- Add diff/preview pane — open a file from tree, see the diff vs branch base. (Reuse
dialog-diff.tsxpatterns.) End: I can review work withoutgit diffin another window. - Add terminal pane — embedded terminal scoped to active task's worktree. End: I can run tests/builds without context-switching.
- Add status flow —
in_progress → in_review → done, with a checks pane showing test/build status per task. End: full Conductor parity.
Each step is mergeable and demoable. The order is layout-first → engine-correct → ergonomics → polish.
type TaskStatus =
| "backlog"
| "in_progress"
| "in_review"
| "done"
| "canceled"
| "error";
type Task = {
id: string; // ulid
title: string; // user-supplied, free text
repo: string; // absolute path to source repo
branch: string; // e.g. sma1lboy/missoula-v1
worktreePath: string; // absolute path to git worktree
sessionId: string | null; // Claude Code session uuid, set after first run
status: TaskStatus;
createdAt: string; // ISO
updatedAt: string; // ISO
};
type TaskIndex = {
version: 1;
tasks: Task[];
};Stored at ~/.kobe/tasks.json. Single writer (the running kobe instance). Single reader for now.
Messages are not in this index. Messages live in Claude Code's JSONL files; we read them via AIEngine.readHistory(sessionId).
Tech stack lock-in: TS + opentui + Solid + Bun.✅ Locked 2026-05-08.- City codename → real name: when do we rename
kobe? Worktree root✅ Updated 2026-06-06: new kobe-created worktrees live at~/.kobe/worktrees/<repo-key>/<slug>/; repo-local<repo>/.kobe/worktrees/<slug>/and legacy<repo>/.claude/worktrees/<slug>/tasks remain supported. The earlier repo-local roots were retired so users do not need repo-level.gitignoreentries for kobe runtime worktrees.- Branch naming: auto-generate (
kobe/<slug>-<id>) or prompt? Conductor auto-generates from task title. - Concurrency cap: max simultaneous running tasks? (Claude Code rate-limits; we should respect.) Suggestion: 4 concurrent, configurable. OPEN.
- Phase 2 ref repo: when does the Conductor-backend reference repo land in
refs/? - Should we add
refs/claude-squad? It's the closest TUI competitor; reading it before MVP would sharpen positioning. - vibe-kanban has been added to
refs/(BloopAI/vibe-kanban). It's sunsetting, so it's an archive not a competitor. Use as interface reference for the AI engine port.
- Cloud sync, multi-machine state.
- Team collaboration / shared task lists.
- Non-Claude-Code engines (we keep the seam, but only ship one impl).
- Conductor-as-backend (Phase 2).
- Production web/mobile UI.
kobe webexists as an early experimental local dashboard as of 2026-06-09; it is not the product center. - CI integration beyond "shell out to
gh". - Plugin system for panes (every pane is hardcoded; pluggability is at the engine layer only).
If you find yourself reaching for any of the above in Phase 1, stop and ask first.