Design doc. Not implemented yet. Captures the decision shape so a future agent (human or otherwise) picks up implementation with full context.
Sibling of
bridge.md: that doc covers the MCP-bridge surface (long-lived stdio child ofclaude); this doc covers a short-lived CLI surface that the model drives from itsBashtool. MCP bridge stays in tree as a fallback; CLI becomes the recommended path.Linear epic: TBD (file before P1 work starts).
The MCP bridge works but has three structural problems that show up in practice:
-
Lifecycle entanglement. The bridge subprocess is a child of
claude, not kobe. When the orchestrator SIGKILLs a wedged session, the bridge sometimes survives as a PPID=1 zombie. We added a PPID-watcher (src/cli/mcp-bridge.ts:279-283) after observing ~55 accumulated zombies in a single day of dev. This is a permanent tax on a long-lived design. -
Connection state. The bridge holds an open Unix socket to kobe for the full duration of the
claudesession. Any daemon restart,kobed restart, or socket drop yanks the rug out from under an in-flight tool call. Reconnection logic is non-trivial and the failure mode (silent "tool unavailable") is hostile to users. -
Discoverability + portability. MCP only helps inside Claude Code. The user runs kobe under Codex too, and may run it under Cursor / OpenClaw / Hermes / a custom agent. Every one of these shells out to
bashhappily; not every one of them speaks MCP, and none of them speak it the same way.
A kobe api <verb> subcommand sidesteps all three. Each call is one
short-lived process: open socket → one RPC → print JSON → exit. No
zombie surface, no reconnect logic, and any agent that has a Bash
tool can use it. Failure mode is a non-zero exit code with a JSON
error on stderr — exactly what shell scripting already knows how to
handle.
Three deliverables:
- One
kobebinary.kobedcollapses intokobe daemon .... Thekobedshim either stays for one minor release as an alias, or gets dropped now — see §6. kobe api <verb>subcommand surface. Five verbs, mapped 1:1 to existing daemon protocol methods. Stdout = newline-terminated JSON.- Bundled skill + README path.
kobe skill installwrites a SKILL.md that teaches the model when and how to use these verbs. README documents the install.
Non-goals (deliberately):
- Removing the MCP bridge code. It stays in tree for installs that already use it. We just stop recommending it.
- Auth / token / network exposure on the daemon socket. Same posture as today — local Unix-socket only.
- A "remote kobe" mode. Single-host scope.
Five verbs. Each takes flag-style args (--task-id ID, not positional)
so the skill examples stay readable and tab IDs / paths with spaces
don't trip parsers.
| verb | flags | daemon method | returns |
|---|---|---|---|
kobe api spawn-task |
--repo PATH --prompt TEXT [--title T] [--base-branch B] |
task.spawn |
task JSON (id, branch, worktree, status) |
kobe api create-tab |
--task-id ID [--title T] |
chat.tab.create |
tab JSON (id, title) |
kobe api send |
--task-id ID --prompt TEXT [--tab-id TID] |
chat.send |
{ ok: true } |
kobe api get-task |
--task-id ID |
reads task.list snapshot, filters |
task JSON |
kobe api get-tab |
--task-id ID --tab-id TID |
reads task snapshot | tab JSON (incl. last N messages) |
- Default: one JSON object per call, written to stdout, terminated
by
\n. Exit code 0. - Errors: JSON object
{ "error": { "message": "...", "code": "..." } }to stderr, exit code non-zero. Never mixed with stdout — that waykobe api list-tasks | jq '.[].id'doesn't choke on error text. (Nolist-tasksin the v1 surface, but the principle stands if/when we add it.) --prettyflag: pretty-print stdout JSON for human inspection. Off by default — machines first, humans second.- No stdin RPC. Every verb takes its full payload in argv. Avoids the "did the agent forget to close stdin" failure mode.
list-tasks: the agent rarely needs to enumerate; it already has task IDs from prior calls. Add when a real use case shows up.wait/ blocking poll: the skill teachessleep + get-taskloops rather than us implementing a server-side wait. Simpler to debug, fewer wedge modes.archive/delete: hard rule says no deletion from automation. Keep destructive ops in the TUI.interrupt,steer,permission-mode,modelchanges: power-user TUI flows. Not the agent's job.
The daemon protocol has ~25 request types (packages/kobe-daemon/src/daemon/protocol.ts).
Most are TUI-driven (focus changes, draft updates, plan-usage polling).
The five above are the minimum complete set for fan-out + report
back, which is the only agent workflow we want to optimize for in v1.
Anything else, the agent can do inside its own chat — it doesn't need
to drive kobe.
kobe api requires a running daemon. Two options:
Option A — hard requirement. If ~/.kobe/run/daemon.sock is
absent, print kobe api: no daemon (run \kobe daemon start`)` to
stderr, exit 2. The agent surfaces this to the user.
Option B — auto-start on demand. If the socket is absent, spawn a
daemon (same path as connectOrStartDaemon already takes in
bin/kobed.ts), wait for ready, then run the RPC.
Recommendation: A, with a single nudge: when the user runs kobe
for the first time and starts the TUI, the TUI's daemon is already
running. The only path where this matters is "user installed kobe but
hasn't launched the TUI yet, and the agent tries to spawn a task" —
rare, and "tell me to run a thing" is a fine error for that case.
Open for §8.
The CLI alone doesn't make the agent use kobe. The skill does.
# kobe — parallel coding tasks from your shell
When the user asks you to "try N approaches in parallel", "fan out",
"compare implementations side-by-side", or to split exploration into
subtasks: prefer spawning kobe tasks over doing N attempts
sequentially in one chat.
## How
- Spawn each subtask: `kobe api spawn-task --repo $PWD --prompt "..."`
Returns JSON with `id`, `worktree_path`, `branch`. Read `id`.
- Cap fan-out at 3-4 in parallel. Each gets its own scoped prompt
(don't dump the full conversation).
- Poll status: `sleep 5; kobe api get-task --task-id <id>` until
`status` is `idle` or `awaiting-approval`. Don't tight-loop.
- Read results: `kobe api get-tab --task-id <id> --tab-id <tab>`.
- Tell the user what was spawned, with IDs, so the sidebar reads back
correctly.
## Don't
- Single simple tasks → just do it in your own chat. No spawn.
- Recursive spawn from inside a spawned task. There is no recursion
guard yet; you'll starve the concurrency cap.
- Use `kobe api send` as a chat channel — every message is a full
agent turn, expensive.
This is roughly the same content as the MCP-targeted skill notes in
bridge.md §4, retargeted to Bash invocation.
Same options as bridge.md §4 but for a SKILL.md file:
- A — auto-write on first
kobelaunch. Zero steps, but pollutes~/.claude/skills/without consent. - B —
kobe skill installsubcommand. User runs once; subcommand writes to~/.claude/skills/kobe/SKILL.md, diff-prompt if exists. - C — first-launch onboarding banner in the TUI.
Recommended: B, same as in bridge.md. Project-level overrides
(<repo>/.claude/skills/kobe/SKILL.md) come for free. kobe diagnose
reports skill: not installed so the user has a discoverable hint.
A kobe skill uninstall mirror is cheap and worth adding.
This is the prerequisite the user called out before any of the API work lands.
packages/kobe/package.jsondeclares two bins:kobe→dist/cli/index.jskobed→dist/bin/kobed.js
kobed start|stop|status|restartis the only surface. ~130 lines.
Move every kobed subcommand under kobe daemon:
| was | becomes |
|---|---|
kobed start |
kobe daemon start |
kobed stop |
kobe daemon stop |
kobed status |
kobe daemon status |
kobed restart |
kobe daemon restart |
Implementation: packages/kobe/src/cli/daemon-cmd.ts exports
runDaemonSubcommand(argv); src/cli/index.ts routes kobe daemon ... to it. The body is mostly a copy-paste from
src/bin/kobed.ts — same KobeDaemonClient, same socket/pid paths.
kobed gets removed from package.json bin in the same release that
introduces kobe daemon .... CHANGELOG entry calls out the rename so
any user with kobed restart in a script breaks loudly the first
time, not silently. We're pre-1.0; semver permits it, and the
discoverability of kobe daemon ... (visible in kobe --help) more
than pays back the one-time muscle-memory disruption.
No shim, no alias. Two-surface tax avoided.
src/bin/kobed.tsbecomes a thin re-export (or deletes entirely if hard-cut wins).- All docs grep-replace
kobed→kobe daemon. Search hits:AGENTS.md,HANDOFF.md,docs/design/daemon.md,docs/design/bridge.md, scripts underpackages/kobe/scripts/. bun runscripts that referencekobedget updated.
Three new sections in packages/kobe/README.md, ordered for a new
reader:
- "Using kobe from another agent" — short rationale, the
kobe apiverb table, one example shell session. - "Install the skill" —
kobe skill install, what file it writes, how to uninstall, mention of project-level overrides. - "From Bash" — the canonical example: spawn one parallel task, poll for completion, read the result.
The existing TUI sections stay first — kobe is a TUI product; the API is for its own spawned agents.
| # | question | options | status |
|---|---|---|---|
| 1 | kobed back-compat |
hard cut / one-release shim / indefinite alias | decided: hard cut (see §6) |
| 2 | verb shape | kobe api spawn-task / kobe task spawn |
recommended: kobe api spawn-task |
| 3 | output default | JSON / pretty | recommended: JSON, --pretty for humans |
| 4 | daemon missing | hard error / auto-start | recommended: hard error |
| 5 | skill install | command / first-launch / banner | recommended: kobe skill install |
| 6 | drop MCP bridge | now / later / keep forever | recommended: keep forever as fallback |
| 7 | rename TUI launch | kobe (today) / kobe tui (explicit) |
recommended: kobe stays |
Items 2-7 lock during P2 implementation unless contested.
Each phase is one PR, green on its own, mergeable independently.
| phase | PR scope | gate |
|---|---|---|
| P1 | Merge kobed → kobe daemon .... Resolve §8.1. |
kobe daemon status works; old kobed either errors with rename hint or aliases. |
| P2 | kobe api <verb> subcommands wired to KobeDaemonClient. All 5 verbs from §3. |
Smoke test: spawn a task from bash, observe sidebar update. |
| P3 | kobe skill install + bundled SKILL.md under packages/kobe/share/skills/kobe/. |
Install on a fresh ~/.claude and read back the file. |
| P4 | README rewrite + AGENTS.md / HANDOFF.md / bridge.md cross-links updated. | Manual: a new user can install + spawn a task in <5 min. |
Total estimate: 4 small PRs, ~150-300 LOC each excluding generated docs.
Concrete enough that any agent picks up a phase and starts typing. Phases are independent PRs (per §9); each is green on its own. The P-numbering mirrors §9.
Files added
-
packages/kobe/src/cli/daemon-cmd.ts— NEW. Owns the four subcommands. Body is a near-direct port ofsrc/bin/kobed.ts:9-128with one signature change (noargv[2]shift; the dispatcher passesrestalready trimmed ofdaemon).export async function runDaemonSubcommand(argv: readonly string[]): Promise<void> { const [command = "status"] = argv const socketPath = defaultDaemonSocketPath() const pidPath = defaultDaemonPidPath() // ...same switch on command as src/bin/kobed.ts }
Files modified
packages/kobe/src/cli/index.ts— add one branch inmain(), next to the existingmcp-bridgeroute:if (subcommand === "daemon") { const { runDaemonSubcommand } = await import("./daemon-cmd.ts") await runDaemonSubcommand(rest) return }
packages/kobe/scripts/build.ts— drop./src/bin/kobed.tsfromentrypoints, drop./dist/bin/kobed.jsfromOUT_FILES. Update the JSDoc that mentionskobedbin output.packages/kobe/scripts/compile.ts— verify nothing else references the kobed entry; remove if it does.packages/kobe/package.json— delete"kobed": "dist/bin/kobed.js"line frombin.
Files deleted
packages/kobe/src/bin/kobed.ts— full delete. (Hard rule: user explicitly authorized this delete via the §8.1 decision.)packages/kobe/src/bin/directory — empty after the above; remove.
Doc grep-replace (P1 part)
AGENTS.md,HANDOFF.md:kobed start→kobe daemon start, etc.docs/design/daemon.md,docs/design/bridge.md: same.packages/kobe/README.md: same.packages/kobe/CHANGELOG.md: new entry for the next version with the rename callout (single line — users hit it once on upgrade, this is their warning).
Test surface
test/daemon/*— most tests spawn the daemon viaconnectOrStartDaemon, not via thekobedbin, so behavior is unchanged. Grep for"kobed"to catch any string-literal tests and retarget tokobe daemon.
Gate
bun run typecheck && bun run test:fast && bun run test:socket
kobe daemon start # spawns daemon
kobe daemon status # JSON dump
kobe daemon stop
Files added
-
packages/kobe/src/cli/api-cmd.ts— NEW. Single file dispatcher; five verbs are small enough to live in-file under ~250 LOC.Shape:
import { KobeDaemonClient } from "../client/index.ts" import { defaultDaemonSocketPath } from "../daemon/paths.ts" type Flags = ReadonlyMap<string, string> export async function runApiSubcommand(argv: readonly string[]): Promise<void> { const [verb, ...rest] = argv const { flags, pretty } = parseFlags(rest) const client = new KobeDaemonClient(defaultDaemonSocketPath()) try { await connectOrFail(client) switch (verb) { case "spawn-task": return emit(await spawnTask(client, flags), pretty) case "create-tab": return emit(await createTab(client, flags), pretty) case "send": return emit(await send(client, flags), pretty) case "get-task": return emit(await getTask(client, flags), pretty) case "get-tab": return emit(await getTab(client, flags), pretty) default: fail(`unknown verb: ${verb}`, "BAD_VERB") } } finally { client.close() } }
Per-verb bodies are straight pass-through to
client.request(...):async function spawnTask(c: KobeDaemonClient, f: Flags) { return c.request("task.spawn", { repo: required(f, "repo"), prompt: required(f, "prompt"), title: f.get("title"), baseRef: f.get("base-branch"), }) }
connectOrFaildistinguishesENOENT(daemon not running) from other errors and emits the recommendedBAD_DAEMONerror verbatim per §4.
get-task / get-tab decision (see §3)
Option A — add task.get to the daemon protocol so get-task is a
single round-trip. ~15 LOC in daemon/protocol.ts + daemon/server.ts.
Option B — fetch task.list, filter for the id client-side. Zero
protocol change, one extra serialization round.
Recommended: A. The protocol already has task.archive,
task.rename, etc. — a task.get belongs in the set. The bridge
RPC already exposes get_task directly off the orchestrator, so the
behavior is exactly what we want.
get-tab builds on the result of task.get (tabs are inline on the
serialized task) and combines it with chat.history for the actual
messages.
Files modified
packages/kobe/src/cli/index.ts— one new branch:if (subcommand === "api") { const { runApiSubcommand } = await import("./api-cmd.ts") await runApiSubcommand(rest) return }
packages/kobe-daemon/src/daemon/protocol.ts— addtask.gettoDaemonRequestName.packages/kobe-daemon/src/daemon/server.ts— handle the new case (oneorch.getTask(taskId)call).
Test surface
test/cli/api-cmd.test.ts— NEW. Spin up a daemon against a tmpKOBE_HOME_DIR, execbun src/cli/index.ts api spawn-task --repo ..., parse stdout JSON, verify expected fields. Repeat for each verb.
Gate
End-to-end smoke from Bash:
kobe daemon start
TASK=$(kobe api spawn-task --repo $PWD --prompt "say hi" | jq -r .taskId)
kobe api get-task --task-id $TASK | jq .status
kobe api create-tab --task-id $TASK --title "exploration"
kobe api send --task-id $TASK --prompt "any update?"
kobe daemon stop
Files added
-
packages/kobe/share/skills/kobe/SKILL.md— NEW. ~60-line skill content from §5. -
packages/kobe/src/cli/skill-cmd.ts— NEW. Two commands:install,uninstall.Install logic:
- Resolve bundled SKILL.md path. In dev:
import.meta.url-relative../../share/skills/kobe/SKILL.md. In production npm install:dist-relative — needsscripts/build.tsto copyshare/intodist/share/so the file is reachable post-bundle. - Target path:
${process.env.HOME}/.claude/skills/kobe/SKILL.md. - If target exists with identical content → print "already installed" + path; exit 0.
- If target exists with different content → print diff (or just a
"differs" warning + show byte counts), prompt
overwrite / skip / cancel.--yesskips prompt for scripts. - Else →
mkdir -p+ write + chmod 0644. Print the path.
Uninstall: best-effort
rmof the file (NOT the directory; user may have other kobe-related skill files). Print what was removed. - Resolve bundled SKILL.md path. In dev:
Files modified
packages/kobe/src/cli/index.ts— routeskillsubcommand.packages/kobe/scripts/build.ts— copyshare/→dist/share/post-Bun.build. ~5 LOCcp -requivalent.packages/kobe/package.jsonfiles— addshareso npm includes it in the published tarball. (Or rely on thedist/share/path alone; depends on whether SKILL.md is shipped raw or only as dist copy. Recommenddist/share/only — single source of truth.)packages/kobe/src/cli/diagnose.ts— add askill: installed | not installedline that reads~/.claude/skills/kobe/SKILL.md.
Gate
kobe skill install # writes ~/.claude/skills/kobe/SKILL.md
kobe diagnose | grep skill
kobe skill install # idempotent
kobe skill uninstall
Files modified
packages/kobe/README.md— add three sections after the existing TUI overview:- "Using kobe from another agent": rationale + the §3 verb table
- one example shell session (the §11 P2 gate block, lightly edited for readability).
- "Install the skill":
kobe skill install+ what it writes + project-level override path (<repo>/.claude/skills/kobe/SKILL.md). - "Daemon":
kobe daemon start / stop / status / restart(replaces any existingkobedmention).
- "Using kobe from another agent": rationale + the §3 verb table
docs/design/bridge.md— add a top-of-doc note: "the CLI API incli-api.mdis now the recommended path; this MCP bridge stays as a fallback for installs that already use it." No content removed — the doc still documents the live MCP code.AGENTS.md,HANDOFF.md— already grep-replaced in P1; verify the README rewrite didn't leave dangling references.packages/kobe/CHANGELOG.md— final entry per release covering all four phases (kobedrename + newkobe api+ skill installer + docs).
Gate
Manual: new user reads README, runs kobe daemon start,
kobe skill install, then asks Claude to "spawn 3 parallel tasks to
implement X three different ways" and the model uses
kobe api spawn-task without further prompting.
packages/kobe/src/cli/index.ts— current subcommand router (add,diagnose,update,theme,mcp-bridge).packages/kobe/src/bin/kobed.ts— what gets merged intokobe daemon ....packages/kobe/src/cli/mcp-bridge.ts— MCP path that stays as fallback.packages/kobe-daemon/src/daemon/protocol.ts— full daemon RPC surface; the fivekobe apiverbs are a strict subset.packages/kobe-daemon/src/client/index.ts—KobeDaemonClient, the ready-made transport everykobe apiverb will use.bridge.md— sibling design doc for the MCP-bridge path; this file supersedes its skill-distribution discussion (§4) but keeps the MCP bridge itself in tree as a fallback.