kankaku-claude 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "kankaku",
+  "description": "Records how long Claude Code works on each of your prompts: wall time, waiting time, work time and cost, per prompt, in kankaku's worklog format.",
+  "version": "0.1.0",
+  "author": {
+    "name": "soyunninja"
+  },
+  "homepage": "https://kankaku.io",
+  "repository": "https://github.com/soyunninja/kankaku-claude",
+  "license": "MIT"
+}

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- Phase 1: per-prompt work records from Claude Code hooks. Writes one
+  `WorkRecord` per user prompt to `<KANKAKU_DIR>/worklog.jsonl`, in the same
+  schema the kankaku pi extension writes, so kankaku's existing
+  report/export/hub tooling can consume it unchanged.
+  - Event sourcing per session (`<KANKAKU_DIR>/claude/<session_id>.events.jsonl`)
+    plus pure replay into a fresh `WorkTracker`, since Claude Code hooks are
+    fresh short-lived processes with no persistent in-memory state.
+  - All 9 documented hook events wired: `SessionStart`, `UserPromptSubmit`,
+    `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SubagentStart`,
+    `SubagentStop`, `Stop`, `SessionEnd`.
+  - Per-prompt cost from the statusline's `cost.total_cost_usd`, as a delta
+    across the prompt.
+  - Crash recovery: a dead session with an open prompt is recovered as an
+    `interrupted` record on the next `SessionStart`.
+  - `src/statusline.ts` (a manually wired `statusLine` command) reports the
+    open prompt's elapsed clock and the current cost.
+  - `node src/cli.ts report|status|setup` and the `/kankaku:report`,
+    `/kankaku:status`, `/kankaku:setup` slash commands.
+
+- Manual hub sync via `node src/cli.ts sync [all|status]` and the
+  `/kankaku:sync` slash command (default sync only). No automatic sync hooks;
+  prompts are omitted by default.
+
+### Fixed
+
+- T7: the statusline command is wired globally in `~/.claude/settings.json`,
+  so it runs in every Claude Code session on the machine, plugin loaded or
+  not. It used to write cost into the open project's own
+  `.kankaku/claude/<session_id>.state.json`, creating a placeholder file
+  (`pid: 0`, `cwd: ""`) in whatever project happened to be open and
+  recreating it after `SessionEnd` deleted it — and `isAlive(0)`
+  (`process.kill(0, 0)` signals the whole process GROUP) reported that
+  placeholder alive forever, so crash recovery never swept it.
+  - Cost now lives only under `~/.kankaku/claude/cost/<session_id>.json`
+    (`src/cost-store.ts`, new; node builtins only), never under a project.
+    The statusline only reads a project's state file, read-only, for the
+    open-prompt clock; a missing state file renders `kankaku idle` without
+    creating anything.
+  - `SessionState` no longer has a `cost` field; `mergeCost` is removed.
+  - `isAlive` returns `false` for any non-positive or non-integer pid
+    without calling `process.kill`; `recoverStaleSessions` treats
+    `pid <= 0` as dead independently of `isAlive`'s answer.
+  - `SessionEnd` also deletes the session's cost file; `SessionStart`
+    (non-`compact`) sweeps cost files older than 7 days.
+  - `node src/cli.ts status` reads cost from the cost file.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 soyunninja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# kankaku-claude
+
+A [Claude Code](https://claude.com/claude-code) plugin that records how long
+Claude Code works on each of your prompts, in the same worklog format as the
+[kankaku](https://kankaku.io) pi extension.
+
+## What it measures
+
+One record per user prompt, appended to `<KANKAKU_DIR>/worklog.jsonl`:
+
+- **Wall time** — from the moment you submit a prompt to the moment Claude
+  Code settles it.
+- **Waiting time** — time spent inside an `AskUserQuestion` tool call or
+  waiting on a permission dialog.
+- **Work time** — wall time minus waiting time.
+- **Cost** — the prompt's share of the session's running `total_cost_usd`
+  (see "Limitations" below for how this is derived).
+
+Records are written in kankaku's own `WorkRecord` schema
+(`WORK_RECORD_SCHEMA = 1`), the exact one the kankaku pi extension writes to
+its own `worklog.jsonl`. This means kankaku's existing report and export
+tooling can read this plugin's worklog unchanged. kankaku-claude also exposes
+manual hub sync through kankaku's public hub adapters (below).
+
+## Requirements
+
+- Claude Code with plugin support.
+- Node.js >= 24 on `PATH` (this package's `.ts` sources run directly under
+  Node's built-in type stripping; there is no build step).
+
+## Install
+
+**From a local path (development).** Clone this repository, then point
+Claude Code at it directly:
+
+```bash
+claude --plugin-dir /path/to/kankaku-claude
+```
+
+If your Claude Code version does not recognize `--plugin-dir`, or plugin
+loading has changed since this was written, check your installed version's
+own plugin documentation (`claude --help`, or `/plugin` inside a session) for
+the current local-install flow.
+
+**From a marketplace.** Once this plugin is published to a marketplace:
+
+```
+/plugin marketplace add <marketplace-source>
+/plugin install kankaku@<marketplace-name>
+```
+
+On install, if `package.json` and `package-lock.json` are both present (as
+they are here), Claude Code runs `npm ci --ignore-scripts` for you; a failure
+there never blocks the plugin from loading.
+
+## The manual step you cannot skip
+
+Claude Code plugins cannot set `statusLine` for themselves — there is no
+programmatic way for a plugin to add a `statusLine` entry to your settings.
+The statusline is also the *only* documented source of per-prompt cost
+(`cost.total_cost_usd`); hooks never receive it. So, once installed, run:
+
+```
+/kankaku:setup
+```
+
+and paste the printed `statusLine` block into `~/.claude/settings.json`
+(merge it with whatever is already there rather than overwriting the file).
+Without this step, kankaku-claude still records wall/waiting/work time, but
+every record's cost stays unset.
+
+Because this settings.json entry is global, the statusline command runs in
+every Claude Code session on the machine, plugin loaded or not — including
+projects that never installed kankaku-claude. It writes only to
+`~/.kankaku/claude/cost/<session_id>.json` (never under any project) and
+only reads a project's own state file, so an unrelated session never leaves
+anything behind in whatever project happens to be open.
+
+## Commands
+
+- `/kankaku:report` — a report of recent work, grouped by day (wraps
+  `node src/cli.ts report`).
+- `/kankaku:status` — the sessions kankaku-claude currently has state for:
+  session id, whether its process is still alive, whether a prompt is open,
+  and the last cost the statusline reported (wraps `node src/cli.ts status`).
+- `/kankaku:setup` — prints the `statusLine` snippet described above (wraps
+  `node src/cli.ts setup`).
+- `/kankaku:sync` — manually syncs local work records to the hub (wraps
+  `node src/cli.ts sync`; the slash command does not forward arguments).
+
+The report, status, and setup subcommands are also available directly via
+`node src/cli.ts <report|status|setup>`; `report` accepts `--days N` and
+defaults to the last 7 days.
+
+### Manual hub sync
+
+Configure hub credentials with `KANKAKU_PB_URL`, `KANKAKU_PB_EMAIL`, and
+`KANKAKU_PB_PASSWORD`, or use `~/.kankaku/credentials.json` (the shared
+kankaku hub credential file). Then run `/kankaku:sync` or
+`node src/cli.ts sync` in the project whose worklog you want to upload.
+For options not forwarded by the slash command, use the CLI directly:
+
+| Command | Purpose |
+|---------|---------|
+| `node src/cli.ts sync` | Manually sync the recent window (24 hours by default). |
+| `node src/cli.ts sync all` | Request a full sync. |
+| `node src/cli.ts sync status` | Inspect local pending counts and sync state; no hub network request or credentials required. |
+
+Optional environment settings:
+
+| Variable | Effect |
+|----------|--------|
+| `KANKAKU_MACHINE` | Machine label for uploaded records (defaults to the host name). |
+| `KANKAKU_SYNC_PROMPT` | Prompt privacy: omitted by default; set `truncated` or `full` to include prompts. |
+| `KANKAKU_SYNC_WINDOW_HOURS` | Recent sync window in hours (defaults to 24). |
+| `KANKAKU_SYNC_RECORDS` | Set to `0` to disable uploading raw `work_records` children; consolidated `task_entries` still sync. |
+
+This first slice is **manual-only**: no automatic sync hooks run yet.
+
+## Where the files live
+
+- `<KANKAKU_DIR>/worklog.jsonl` — the append-only log of settled records,
+  shared with (and readable by) kankaku's own tooling.
+- `<KANKAKU_DIR>/claude/<session_id>.events.jsonl` and
+  `<KANKAKU_DIR>/claude/<session_id>.state.json` — kankaku-claude's own
+  per-session working files (event log and small state file). These are
+  implementation detail, not part of the shared worklog format, and are
+  cleaned up once a session ends. Only the hooks ever write this state file;
+  the statusline command only reads it (see below).
+- `~/.kankaku/claude/cost/<session_id>.json` — the per-session cost the
+  statusline last reported, **always under your home directory, never under
+  a project.** The statusline command is wired into `~/.claude/settings.json`
+  globally, so it runs on every Claude Code session on the machine; writing
+  cost next to a project's own state file would litter whatever project
+  happens to be open with another session's data. This directory is
+  owner-only (`0700`), each cost file is `0600`, and a file older than 7
+  days is swept on the next `SessionStart`.
+
+`KANKAKU_DIR` defaults to `.kankaku` (relative to the session's working
+directory); set the `KANKAKU_DIR` environment variable to use an absolute
+path or a different relative one, exactly as the pi extension does.
+
+## Crash recovery
+
+If Claude Code's process is killed mid-prompt (or mid-session), the next
+session's `SessionStart` hook scans for other sessions' state files whose
+process is no longer alive. A dead session with an open prompt is replayed
+and appended as one `status: "interrupted"` record before its files are
+deleted; a dead session with no open prompt just has its files deleted. This
+also runs for the current session's own leftover state at `SessionEnd`.
+
+## Limitations
+
+- **`turns` is always 1 per run.** Claude Code hooks give no way to observe
+  provider-level retries/turns inside one run; every replayed run reports
+  exactly one turn.
+- **No token counts.** Hooks never carry input/output/cache token numbers,
+  only the statusline's aggregate `total_cost_usd`; per-record `usage` token
+  fields stay at zero, cost is the only populated figure.
+- **Cost is a per-prompt delta of the session total, from the statusline,
+  and needs the manual setup step.** A tiny race is possible: the statusline
+  can render after `Stop` has already computed the delta, in which case a
+  sliver of one prompt's cost is attributed to the next prompt instead.
+- **A permission wait ends at the next hook event, not when you actually
+  click.** There is no documented hook that fires the moment you answer a
+  permission dialog, so the waiting span closes at whatever hook fires next
+  (typically the tool's own `PreToolUse`), not at the click itself.
+- **A background `Agent`/`Task` subagent span ends when the tool call
+  returns, not when the subagent actually finishes.** Claude Code does not
+  document a link between a `SubagentStart`/`SubagentStop` pair and the
+  `tool_use_id` that launched it, so kankaku-claude cannot join them; the
+  subagent's own time is not separately measured here.
+- **Hub sync is manual-only.** Use `/kankaku:sync` or the direct CLI as
+  described above; no automatic sync hooks run yet. Prompts are omitted
+  from uploads unless `KANKAKU_SYNC_PROMPT` is `truncated` or `full`.
+
+See [kankaku.io](https://kankaku.io) for the pi extension this plugin shares
+its worklog format with.

package/commands/report.md

@@ -0,0 +1,9 @@
+---
+description: Show a kankaku report of recent Claude Code work (wall, waiting, work time and cost, per prompt)
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI report command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" report

package/commands/setup.md

@@ -0,0 +1,12 @@
+---
+description: Print the statusLine snippet to add to ~/.claude/settings.json so kankaku can read per-prompt cost
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI setup command and show its output to the user verbatim.
+Then tell the user, briefly: paste the printed `statusLine` block into their
+`~/.claude/settings.json` (merging it if that file already has other keys),
+because a Claude Code plugin cannot set `statusLine` for itself — the
+statusline is the only documented source of per-session cost.
+
+!node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" setup

package/commands/status.md

@@ -0,0 +1,9 @@
+---
+description: Show the current kankaku session states tracked for this project (pid liveness, open prompt, last cost)
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI status command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" status

package/commands/sync.md

@@ -0,0 +1,14 @@
+---
+description: Manually sync local kankaku work records to the hub
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI sync command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" sync
+
+For a full sync or local sync status, use the direct CLI instead:
+`node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" sync all` or
+`node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" sync status`.
+This slash command runs the default sync only; it does not forward arguments.

package/hooks/hooks.json

@@ -0,0 +1,103 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/src/hook.ts\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "kankaku-claude",
+  "version": "0.1.0",
+  "description": "Claude Code plugin that records how long the agent works on each user prompt, in kankaku's worklog format.",
+  "type": "module",
+  "files": [
+    ".claude-plugin/",
+    "commands/",
+    "hooks/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "tsconfig.json"
+  ],
+  "license": "MIT",
+  "author": "soyunninja",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soyunninja/kankaku-claude.git"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "kankaku": "^0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^5.7.0"
+  }
+}

package/src/claude-pid.ts

@@ -0,0 +1,68 @@
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+
+export interface PsInfo {
+  ppid: number;
+  comm: string;
+}
+
+const SKIP_COMMS = new Set(["sh", "bash", "zsh", "dash", "fish", "node"]);
+const MAX_HOPS = 6;
+
+export interface ResolveClaudePidInput {
+  startPid: number;
+  runPs: (pid: number) => PsInfo | undefined;
+}
+
+/**
+ * Walks ancestors from `startPid` (at most `MAX_HOPS` hops), returning the
+ * first pid whose `comm` basename is not a shell or `node` — the Claude
+ * Code process itself, skipping the shell/node layers a hook can be
+ * launched through. Falls back to `startPid` when `ps` fails or nothing
+ * qualifies within the hop budget.
+ */
+export function resolveClaudePid({ startPid, runPs }: ResolveClaudePidInput): number {
+  let pid = startPid;
+  for (let hop = 0; hop < MAX_HOPS; hop++) {
+    const info = runPs(pid);
+    if (!info) return startPid;
+    if (!SKIP_COMMS.has(basename(info.comm))) return pid;
+    pid = info.ppid;
+  }
+  return startPid;
+}
+
+/** Production `runPs`: `ps -o ppid=,comm= -p <pid>`, bounded to 200ms. */
+export function runPsProcess(pid: number): PsInfo | undefined {
+  try {
+    const out = execFileSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], {
+      timeout: 200,
+      encoding: "utf8",
+    });
+    const match = out.trim().match(/^(\d+)\s+(.+)$/);
+    if (!match) return undefined;
+    const ppid = Number(match[1]);
+    const comm = match[2]?.trim();
+    if (!Number.isFinite(ppid) || !comm) return undefined;
+    return { ppid, comm };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `true` unless `process.kill(pid, 0)` throws with a code other than
+ * `EPERM`. A non-positive or non-integer pid is always `false`, without
+ * calling `process.kill` at all: `pid` 0 signals the whole process GROUP
+ * (T7 — the defect that let a placeholder state file's `pid: 0` read back
+ * as alive forever).
+ */
+export function isAlive(pid: number): boolean {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}

package/src/cli-core.ts

@@ -0,0 +1,100 @@
+import { basename, join } from "node:path";
+import { JsonlWorkLog } from "kankaku/hub";
+import { listStateFiles, resolveKankakuDir } from "./paths.ts";
+import { readState } from "./session-state.ts";
+import { readCost } from "./cost-store.ts";
+import { formatReport } from "./report.ts";
+import { runSyncCli } from "./sync-cli.ts";
+
+export interface CliDeps {
+  env: NodeJS.ProcessEnv;
+  cwd: string;
+  now: () => number;
+  isAlive: (pid: number) => boolean;
+  /** Absolute path to the plugin/repo root (the directory containing `.claude-plugin/`). */
+  pluginRoot: string;
+}
+
+export interface CliResult {
+  stdout: string;
+  exitCode: number;
+  /** Usage or sync error output. */
+  stderr?: string;
+}
+
+const USAGE = "usage: node src/cli.ts <report|status|setup|sync> [--days N]\n";
+
+/** CLI commands, resolved from `deps.cwd`. */
+export async function runCli(argv: string[], deps: CliDeps): Promise<CliResult> {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case "report":
+      return runReport(rest, deps);
+    case "status":
+      return runStatus(deps);
+    case "setup":
+      return runSetup(deps);
+    case "sync":
+      return runSyncCli(rest, deps);
+    default:
+      return { stdout: "", exitCode: 1, stderr: USAGE };
+  }
+}
+
+function runReport(args: string[], deps: CliDeps): CliResult {
+  const days = parseDays(args);
+  const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+  const records = new JsonlWorkLog(kankakuDir).readAll();
+  const stdout = formatReport(records, { now: deps.now(), ...(days !== undefined ? { days } : {}) });
+  return { stdout, exitCode: 0 };
+}
+
+function parseDays(args: string[]): number | undefined {
+  const idx = args.indexOf("--days");
+  if (idx === -1) return undefined;
+  const value = Number(args[idx + 1]);
+  return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function runStatus(deps: CliDeps): CliResult {
+  const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+  const claudeDir = join(kankakuDir, "claude");
+  const files = listStateFiles(claudeDir);
+  if (files.length === 0) {
+    return { stdout: "No active sessions.\n", exitCode: 0 };
+  }
+  const lines = files
+    .sort()
+    .map((file) => formatStatusLine(sessionIdFromStateFile(file), file, deps.isAlive, deps.env));
+  return { stdout: lines.join("\n") + "\n", exitCode: 0 };
+}
+
+function formatStatusLine(
+  sessionId: string,
+  stateFile: string,
+  isAlive: (pid: number) => boolean,
+  env: NodeJS.ProcessEnv,
+): string {
+  const state = readState(stateFile);
+  if (!state) return `${sessionId}  (unreadable state)`;
+  const aliveWord = isAlive(state.pid) ? "alive" : "dead";
+  const promptWord = state.promptOpen
+    ? `prompt open since ${new Date(state.promptOpen.startedAt).toISOString()}`
+    : "idle";
+  const cost = readCost(env, sessionId);
+  const costWord = cost ? `$${cost.totalUsd.toFixed(2)}` : "-";
+  return `${sessionId}  pid ${state.pid} (${aliveWord})  ${promptWord}  cost ${costWord}`;
+}
+
+function sessionIdFromStateFile(file: string): string {
+  return basename(file).replace(/\.state\.json$/, "");
+}
+
+function runSetup(deps: CliDeps): CliResult {
+  const statuslinePath = join(deps.pluginRoot, "src", "statusline.ts");
+  const command = `node "${statuslinePath}"`;
+  const snippet = JSON.stringify({ statusLine: { type: "command", command } }, null, 2);
+  const explanation =
+    "Claude Code plugins cannot set statusLine themselves, so this must be added to ~/.claude/settings.json manually: the statusline is the only documented source of per-session cost.";
+  return { stdout: `${snippet}\n\n${explanation}\n`, exitCode: 0 };
+}

package/src/cli.ts

@@ -0,0 +1,19 @@
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+import { runCli } from "./cli-core.ts";
+import { isAlive } from "./claude-pid.ts";
+
+// src/cli.ts -> src -> repo root (the directory that contains .claude-plugin/).
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const result = await runCli(process.argv.slice(2), {
+  env: process.env,
+  cwd: process.cwd(),
+  now: () => Date.now(),
+  isAlive,
+  pluginRoot,
+});
+
+if (result.stdout) process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(result.stderr);
+process.exit(result.exitCode);