@sma1lboy/kobe 0.5.22 → 0.5.25

package/README.md

@@ -33,6 +33,21 @@ You need two things on `PATH`:
 - [**Bun**](https://bun.sh) ≥ 1.0 — kobe's renderer is opentui, which uses Bun-FFI.
 - [**`claude`** CLI](https://docs.anthropic.com/en/docs/claude-code) — the engine kobe drives. Run `claude --version` to confirm it's installed and signed in.
 
+Optional but recommended (preview pane shows graceful fallbacks otherwise):
+
+- **`chafa`** ≥ 1.8 + **`ffmpeg`** / **`ffprobe`** — image preview (sixel + character grid + animated GIF). Without these, image files show a metadata card with a "preview not supported" hint.
+- **`rsvg-convert`** (`librsvg2-bin`) — SVG → rasterized image preview. Without it, SVGs fall back to syntax-highlighted XML source.
+
+| Platform | Install command |
+|---|---|
+| Debian / Ubuntu | `sudo apt install chafa ffmpeg librsvg2-bin` |
+| Fedora | `sudo dnf install chafa ffmpeg librsvg2-tools` |
+| Arch | `sudo pacman -S chafa ffmpeg librsvg` |
+| macOS | `brew install chafa ffmpeg librsvg` |
+| Windows | `winget install hpjansson.chafa Gyan.FFmpeg` |
+
+`bun install` runs a postinstall check and prints any missing pieces with the install command. Set `KOBE_SKIP_DEP_CHECK=1` to silence it in CI.
+
 Then:
 
 ```bash
@@ -173,6 +188,88 @@ an exec bit. The behavior-test driver fixes it lazily on first spawn (see
 validates the repo path before creating; if it's complaining, check that
 `git status` runs cleanly inside the path you typed.
 
+## Driving kobe from another agent
+
+Inside kobe, the `claude` (or `codex`, etc.) you are talking to can call back
+out and spawn more kobe tasks — useful when you ask it to "try three approaches
+in parallel" instead of doing them sequentially in one chat. The mechanism is a
+small CLI surface; design rationale lives in [`docs/design/cli-api.md`](../../docs/design/cli-api.md).
+
+### Daemon lifecycle
+
+A `kobe daemon` process holds your tasks and chat sessions. The TUI auto-starts
+one on first launch; in scripts you may want to manage it explicitly.
+
+```bash
+kobe daemon start     # spawn detached, listen on the unix socket
+kobe daemon status    # JSON status (pid, uptime, attached clients, task count)
+kobe daemon restart   # graceful stop + start
+kobe daemon stop      # tell the daemon to drain and exit
+```
+
+> Pre-0.6 builds shipped a separate `kobed` binary for the same commands. It
+> was removed in favor of the single-bin surface (KOB-136); any script with
+> `kobed restart` needs a one-time rename to `kobe daemon restart`.
+
+### `kobe api <verb>` — five shell verbs
+
+Each call is a short-lived process: open the daemon socket, do one RPC, print
+JSON to stdout, exit. Any tool with a `Bash` capability (Claude Code, Codex,
+Cursor, a custom agent) can drive it.
+
+| verb | flags | what it does |
+|---|---|---|
+| `spawn-task` | `--repo PATH --prompt TEXT [--title T] [--base-branch B]` | Create a new task + worktree + chat session. |
+| `create-tab` | `--task-id ID [--title T]` | Open an extra chat tab on an existing task. |
+| `send`       | `--task-id ID --prompt TEXT [--tab-id TID]` | Resume the task's session with a new prompt. |
+| `get-task`   | `--task-id ID` | Read task metadata (status, branch, worktree, tabs). |
+| `get-tab`    | `--task-id ID --tab-id TID` | Read a single tab off the task. |
+
+Output is one JSON object on stdout, `\n` terminated, exit 0. Errors land on
+stderr as `{"error":{"message":"...","code":"..."}}` with a non-zero exit.
+Add `--pretty` for human inspection.
+
+Fan-out from a shell:
+
+```bash
+T1=$(kobe api spawn-task --repo "$PWD" --prompt "Approach A: state machine"   | jq -r .taskId)
+T2=$(kobe api spawn-task --repo "$PWD" --prompt "Approach B: event sourcing"  | jq -r .taskId)
+T3=$(kobe api spawn-task --repo "$PWD" --prompt "Approach C: reducer pattern" | jq -r .taskId)
+
+# Tell the user three tasks are running — they'll appear in the sidebar.
+echo "Spawned $T1 $T2 $T3"
+
+# Poll until each settles.
+for ID in $T1 $T2 $T3; do
+  until [ "$(kobe api get-task --task-id "$ID" | jq -r .task.status)" = "idle" ]; do
+    sleep 10
+  done
+done
+```
+
+If the daemon isn't running, `kobe api ...` exits 2 with
+`{"error":{"code":"BAD_DAEMON",...}}` on stderr. Start it with
+`kobe daemon start` (or just launch the TUI).
+
+### Install the agent skill
+
+`kobe api` gives the *capability*. The bundled SKILL.md gives the model the
+*intent* — when to fan out, how to scope subtask prompts, how to read results
+back. Install it once:
+
+```bash
+kobe skill install              # writes ~/.claude/skills/kobe/SKILL.md
+kobe skill install --yes        # overwrite an existing copy
+kobe skill uninstall            # remove it
+```
+
+After install, Claude Code automatically picks up the skill on its next launch.
+For project-level overrides, copy the file to `<repo>/.claude/skills/kobe/SKILL.md`
+and customise — Claude Code's discovery order is project > user > none.
+
+`kobe diagnose` reports whether the skill is installed, which is the
+fastest way to confirm.
+
 ## Coming later
 
 - Homebrew tap (mirroring [`sma1lboy/homebrew-codefox`](https://github.com/sma1lboy/homebrew-codefox)) so you can `brew install kobe` without touching Bun directly.
@@ -190,22 +287,22 @@ bun run dev          # boots the 5-pane TUI under KOBE_DEV=1 (no update chip, et
 bun run test         # normal suite: fast tests + serial socket tests
 bun run test:behavior  # slow PTY suite; only run for user-visible TUI behavior
 bun run typecheck    # strict tsc
-bun run build        # produces ./dist/index.js for `npm publish`
+bun run build        # produces ./dist/cli/index.js for npm
 ```
 
 Architecture, design philosophy, and the team-of-agents operating model live in:
 
-- [`docs/DESIGN.md`](./docs/DESIGN.md) — design philosophy, tech stack lock-in.
-- [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — module map and current state.
-- [`docs/HARNESS.md`](./docs/HARNESS.md) — the agent self-test contract.
-- [`docs/PLAN.md`](./docs/PLAN.md) — phase / wave plan.
-- [`HANDOFF.md`](./HANDOFF.md) — current direction + what just shipped.
+- [`docs/DESIGN.md`](../../docs/DESIGN.md) — design philosophy, tech stack lock-in.
+- [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) — module map and current state.
+- [`docs/HARNESS.md`](../../docs/HARNESS.md) — the agent self-test contract.
+- [`docs/PLAN.md`](../../docs/PLAN.md) — phase / wave plan.
+- [`HANDOFF.md`](../../HANDOFF.md) — latest session state and follow-ups.
 
 ### Releasing
 
 Bump `package.json`, move `## [Unreleased]` in `CHANGELOG.md` to the new
 version section, commit, then push the matching `vX.Y.Z` tag. The release
-workflow ([`.github/workflows/release.yml`](./.github/workflows/release.yml))
+workflow ([`.github/workflows/release.yml`](../../.github/workflows/release.yml))
 runs typecheck + unit tests + build, asserts the tag matches `package.json`,
 then `npm publish --provenance` and creates a GitHub release with the
 changelog section as the body.