throughline 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kitepon
+
+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,329 @@
+# Throughline
+
+**Cut ~90% of Claude Code's context usage while keeping nearly all the memory.**
+
+In a typical Claude Code session, **80% of the context window is tool I/O** —
+file reads, Bash output, grep results. This data is consumed the moment Claude
+acts on it, but it stays in the context forever, pushing you toward the window
+limit.
+
+Throughline fixes this by separating conversation content by **type, not time**:
+
+```
+Without Throughline (50 turns, no /clear):
+  Context = user text + assistant text + tool I/O + system messages
+          ≈ 125,000 tokens (80% is tool I/O you'll never re-read)
+
+With Throughline (50 turns → /clear → resume):
+  Context = recent 20 turns of conversation text (L2)
+          + older 30 turns as one-line summaries (L1)
+          + zero tool I/O (L3 — retired to SQLite, on-demand)
+          ≈ 13,000 tokens — same decisions, same context, 90% lighter
+```
+
+Unlike MemGPT or LangChain's SummaryBufferMemory which compress by **recency**
+(old = summarized), Throughline separates by **content type**: human-readable
+conversation stays, machine-generated tool output retires. This is purpose-built
+for coding assistants where tool I/O is heavy but transient.
+
+The retired L3 data isn't lost — Claude can pull it back on demand via
+`throughline detail <time>` when a past turn's tool output becomes relevant
+again.
+
+Throughline also ships a multi-session **token monitor** that reads real
+Anthropic API usage from the transcript JSONL (no `length / 4` heuristics).
+
+---
+
+## Quick Start
+
+```bash
+npm install -g throughline
+throughline install
+```
+
+That's it. `install` registers Throughline's hooks in `~/.claude/settings.json`
+(user scope), so every Claude Code project on your machine picks it up
+automatically. No per-project wiring required.
+
+Start any Claude Code session and your turns will begin flowing into
+`~/.throughline/throughline.db` in the background.
+
+---
+
+## Three-layer memory model (schema v4)
+
+| Layer | Name       | Where it lives        | Content                                                    | Cost per turn |
+| ----- | ---------- | --------------------- | ---------------------------------------------------------- | ------------- |
+| **L1** | Skeleton  | injected when old     | one-line Haiku-generated summary of the turn               | ~10 tok       |
+| **L2** | Body      | injected when recent  | user text + assistant reply, verbatim                      | full natural  |
+| **L3** | Detail    | SQLite only           | tool I/O, system messages, images (on-demand via command)  | heavy, retired |
+
+The layers are **complementary and disjoint** — nothing is duplicated across
+them. Thinking blocks are discarded entirely (not stored at either layer) to
+match the stock Claude Code behavior.
+
+On `SessionStart`, Throughline rebuilds the context from SQLite and
+injects it as plain text:
+
+- The **most recent 20 turns** are injected as full L2 (`bodies`) text
+- **Older turns** are injected as L1 (`skeletons`) one-liners
+- L3 stays in SQLite and is retrieved on demand via `/sc-detail <time>`
+
+L1 summaries are generated by **Claude Haiku 4.5** via a subprocess
+(`claude -p --model claude-haiku-4-5-*`), reusing your Claude Max login — no API
+key required. Summarization is lazy: for sessions that stay under 20 turns,
+Haiku is never invoked, so short tasks cost zero summarization time.
+
+All three layers (L1/L2/L3) have working write paths as of schema v5.
+`/sc-detail HH:MM:SS` returns user/assistant text (L2) plus a kind-grouped view
+of tool inputs, tool outputs, and hook output captured at L3 for that turn.
+
+---
+
+## `/clear`-safe with memory rebonding
+
+When you run `/clear`, the conversation transcript is discarded, but the SQLite
+database is untouched. On the next session start:
+
+1. `SessionStart` hook fires with a new `session_id`
+2. Throughline finds the previous session in the same project
+3. It **rebonds** all `skeletons` / `bodies` / `details` rows from the previous
+   session into the new session (via `UPDATE session_id = ?`) inside a
+   `BEGIN IMMEDIATE` transaction
+4. A handover banner is injected:
+   `## Throughline: セッション記憶（N ターン引き継ぎ）`
+
+Each row keeps its **origin_session_id**, so memories accumulate through chains
+of `/clear` rather than being lost or overwritten:
+
+```
+S1 (4 turns) -- /clear --> S2 (merges S1, adds 3 turns) -- /clear --> S3 (merges S2, adds 5 turns)
+                           origin=S1×4                                origin=S1×4, S2×3, S3×5
+```
+
+No time-window heuristic, no PID guessing, no ancestor walking. Just a
+deterministic UPDATE inside a SQLite transaction.
+
+---
+
+## Multi-session token monitor
+
+Run:
+
+```bash
+throughline monitor            # all active sessions in the current project
+throughline monitor --all      # every project, every session
+throughline monitor --session <id-prefix>
+```
+
+Example output (real values from a running 1M-context Opus session):
+
+```
+[Throughline] 1 セッション
+▶ Throughline       2ed5039c  ████░░░░░░░░░░░░░░░░  205.1k /  21%  残 794.9k  claude-opus-4-6
+```
+
+- **Token counts are accurate.** Read straight from the latest `message.usage`
+  field in the session transcript JSONL, which is what Anthropic's API actually
+  reported (`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`).
+  No `length / 4` approximation.
+- **1M-context detection** is automatic. It checks the `[1m]` suffix in the
+  transcript, falls back to string matching on `1M context`, and finally
+  promotes to 1M if observed usage exceeds 200k.
+- **Multi-session view.** Each Claude Code session writes its own state file
+  (`~/.throughline/state/<session_id>.json`). The monitor scans the directory
+  every second and displays one row per live session, sorted by last activity.
+  The most recent one is highlighted with `▶`.
+- **Stale hiding.** Sessions that haven't been touched in 15 minutes drop out of
+  the default view; files older than 24 hours are deleted entirely. This is the
+  only time threshold in the system and is used solely for display hygiene — no
+  memory decisions are made from it.
+- **Line-wrap safe.** Each line is truncated to `process.stdout.columns - 1`
+  before drawing, preserving ANSI color codes. The redraw cursor math cannot
+  desync on narrow terminals.
+
+### VS Code auto-start
+
+For contributors working on Throughline itself, a `.vscode/tasks.json` in this
+repo launches `throughline monitor` automatically in a dedicated terminal when
+you open the folder. Drop an equivalent config into your own project's
+`.vscode/tasks.json` to get the same behavior.
+
+---
+
+## Commands
+
+| Command                                        | What it does                                                 |
+| ---------------------------------------------- | ------------------------------------------------------------ |
+| `throughline install`                          | Register hooks in `~/.claude/settings.json` (user scope)     |
+| `throughline install --project`                | Register hooks in `.claude/settings.json` for this repo only |
+| `throughline uninstall`                        | Remove Throughline hooks from the settings file              |
+| `throughline monitor [--all] [--session <id>]` | Run the multi-session token monitor                          |
+| `throughline detail <time>`                    | Retrieve L2 body text and L3 tool I/O for a turn (see below) |
+| `throughline doctor`                           | Check Node version, hook registration, DB writability, PATH  |
+| `throughline status`                           | Print DB statistics (sessions, skeletons, bodies, details)   |
+| `throughline --version`                        | Print the installed version                                  |
+
+Hook subcommands (invoked by Claude Code, not by humans):
+`session-start` (SessionStart), `process-turn` (Stop).
+
+### `throughline detail` — for AI, not humans
+
+`throughline detail` is the escape hatch Claude itself uses to pull archived
+detail back into the context when an L1 summary isn't enough. The injection
+footer explicitly instructs Claude to run this via its Bash tool when a past
+turn's tool I/O becomes relevant.
+
+```bash
+throughline detail 14:23:05          # single timestamp
+throughline detail 14:23-14:30       # timestamp range
+```
+
+Output groups records by `kind`: L2 conversation bodies, then L3 tool input/
+output, then system messages (hook output), then images. Records are scoped to
+the current project's merge chain so Claude only sees turns from its own
+project history.
+
+---
+
+## Requirements
+
+- **Node.js >= 22.5** (for the built-in `node:sqlite` module — no native build
+  required, no `npm install` of SQLite bindings)
+- **Claude Code** with hooks support (`SessionStart`, `Stop`)
+- **Claude Max subscription** (for Haiku-based L1 summarization via `claude -p`)
+- Works on **Windows, macOS, Linux**
+
+Throughline has **zero runtime dependencies**. The published tarball is just
+plain `.mjs` files.
+
+---
+
+## Data layout
+
+```
+~/.throughline/
+├── throughline.db          SQLite database (WAL mode)
+├── haiku-workdir/            Isolated cwd for Haiku subprocess (recursion guard)
+└── state/
+    └── <session_id>.json     Per-session activity state for the monitor
+```
+
+Schema v5:
+
+- `sessions` — one row per `session_id`, with `project_path` and `merged_into`
+- `skeletons` — L1 one-liners, keyed by `(session_id, origin_session_id, turn, role)`
+- `bodies` — L2 verbatim text (user + assistant), same key shape
+- `details` — L3 records with `kind` column (`tool_input` / `tool_output` / `system` / `image`) and `source_id` for idempotent re-processing
+- `injection_log` — audit trail of injection events
+
+All tables carry an `origin_session_id` so rebonded rows keep their lineage
+after a `/clear` chain.
+
+---
+
+## Design principle: no fallback code
+
+Throughline deliberately refuses to swallow unexpected errors.
+Silent `try { … } catch { /* ignore */ }` blocks hide bugs; instead, hooks throw
+and exit with a non-zero status so Claude Code surfaces the failure in `stderr`.
+
+Specifically:
+
+- JSON parse failures → `throw`, not `continue`
+- Missing required fields → `throw new Error(...)`, not `exit(0)`
+- DB transactions → explicit `BEGIN IMMEDIATE` / `ROLLBACK` / re-throw
+- Hook entry points wrap `main()` with a single `.catch` that writes `stderr` and
+  exits with code 1
+
+The only tolerated silent paths are:
+- JSONL per-line parse tolerance (tail partial writes are part of the format spec)
+- State-file corruption recovery (files are idempotently regenerated next turn)
+
+See [`docs/PUBLIC_RELEASE_PLAN.md §0`](docs/PUBLIC_RELEASE_PLAN.md) for the full
+rule.
+
+---
+
+## Haiku recursion defense
+
+L1 summarization spawns `claude -p --model claude-haiku-4-5-*` as a subprocess.
+Without precautions this would recursively fire the same Stop hook on the
+subprocess and infinite-loop. Two defenses stack:
+
+1. **Isolated cwd.** The subprocess runs in `~/.throughline/haiku-workdir/`, a
+   directory that contains no `.claude/settings.json`, so project-local hooks
+   are never picked up by the child.
+2. **Env var guard.** The parent sets
+   `THROUGHLINE_IN_HAIKU_SUBPROCESS=1` in the child env. The Stop hook
+   (`turn-processor.mjs`) exits immediately on line 1 if it sees this variable.
+
+See [`src/haiku-summarizer.mjs`](src/haiku-summarizer.mjs) for the implementation.
+
+---
+
+## Troubleshooting
+
+**Monitor says `待機中 — アクティブなセッションがありません`**
+No session has touched its state file in the last 15 minutes. Send a message in
+Claude Code and the monitor should pick it up within 1 second. If it still does
+not, run `throughline doctor`.
+
+**`throughline install` wrote to the wrong settings file**
+By default, Throughline installs to `~/.claude/settings.json` (user scope, applies
+to all projects). Use `--project` to scope it to the current directory's
+`.claude/settings.json` instead.
+
+**Hooks never fire**
+Run `throughline doctor` — it checks Node version, hook registration, DB
+writability, and PATH resolution. If the binary is not on PATH, reinstall with
+`npm install -g throughline`.
+
+**`node:sqlite` warning on startup**
+Node.js prints `ExperimentalWarning: SQLite is an experimental feature` on stderr.
+This is cosmetic — the module is stable enough for production and is used
+unchanged here.
+
+**Database got corrupted / want a clean slate**
+Delete `~/.throughline/throughline.db` (and the `-shm` / `-wal` companion files)
+and `~/.throughline/state/*.json`. A fresh database with schema v4 is created on
+the next hook fire.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/kitepon-rgb/Throughline.git
+cd Throughline
+npm link                              # Put `throughline` on PATH
+throughline install --project         # Register hooks for this repo only
+node --test src/turn-processor.test.mjs src/session-merger.test.mjs
+```
+
+Run the monitor directly without a global install:
+
+```bash
+node src/token-monitor.mjs
+```
+
+The `.vscode/tasks.json` in this repo auto-launches the monitor when you open
+the folder in VS Code.
+
+---
+
+## Design docs
+
+- [`docs/L1_L2_L3_REDESIGN.md`](docs/L1_L2_L3_REDESIGN.md) — **current design
+  spec** for the L1/L2/L3 differential layer model (schema v4). Authoritative.
+- [`docs/PUBLIC_RELEASE_PLAN.md`](docs/PUBLIC_RELEASE_PLAN.md) — public release
+  plan (CLI surface, package.json layout, § 0 fallback rule)
+- [`docs/archive/`](docs/archive/) — superseded design documents kept for
+  historical reference (original CONCEPT, session-linking experiments, etc.)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/throughline.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * throughline CLI ディスパッチャ
+ * サブコマンドに応じて既存の hook スクリプトへ委譲する。
+ *
+ * 使い方:
+ *   throughline install       # ~/.claude/settings.json に hook を登録
+ *   throughline uninstall     # hook を削除
+ *   throughline process-turn  # Stop hook (Claude Code から呼ばれる)
+ *   throughline session-start # SessionStart hook (Claude Code から呼ばれる)
+ *   throughline detail <時刻> # L2+L3 詳細取得 (Claude が Bash 経由で呼ぶ想定)
+ *   throughline doctor        # 環境チェック
+ *   throughline status        # DB 統計表示
+ *   throughline --version     # バージョン表示
+ *
+ * 注意: schema v4 で capture-tool (PostToolUse) は廃止。L2/L3 は Stop 内で一括処理。
+ *        inject-context (UserPromptSubmit) も廃止。L1/L2 注入は SessionStart で 1 回のみ。
+ */
+
+const [, , cmd, ...rest] = process.argv;
+
+switch (cmd) {
+  case 'install':
+    await (await import('../src/cli/install.mjs')).run(rest);
+    break;
+  case 'uninstall':
+    await (await import('../src/cli/install.mjs')).run(['--uninstall', ...rest]);
+    break;
+  case 'process-turn':
+    await import('../src/turn-processor.mjs');
+    break;
+  case 'session-start':
+    await import('../src/session-start.mjs');
+    break;
+  case 'monitor':
+    await import('../src/token-monitor.mjs');
+    break;
+  case 'detail':
+    (await import('../src/sc-detail.mjs')).run(rest);
+    break;
+  case 'doctor':
+    await (await import('../src/cli/doctor.mjs')).run();
+    break;
+  case 'status':
+    await (await import('../src/cli/status.mjs')).run();
+    break;
+  case '--version':
+  case '-v': {
+    const { createRequire } = await import('node:module');
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    break;
+  }
+  default:
+    await showHelp();
+}
+
+async function showHelp() {
+  const { createRequire } = await import('node:module');
+  const require = createRequire(import.meta.url);
+  const version = require('../package.json').version;
+  console.log(`throughline v${version}
+
+Usage:
+  throughline install         Register hooks in ~/.claude/settings.json
+  throughline uninstall       Remove hooks
+  throughline monitor         Multi-session token monitor (use --all, --session <id>)
+  throughline detail <time>   Retrieve L2+L3 detail for a turn (e.g. 14:23:05 or 14:23-14:30)
+  throughline doctor          Check environment
+  throughline status          Show DB statistics
+  throughline --version       Show version
+
+Hook subcommands (called by Claude Code):
+  throughline session-start   SessionStart hook
+  throughline process-turn    Stop hook
+`);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "throughline",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
+  "keywords": [
+    "claude-code",
+    "hooks",
+    "context-compression",
+    "llm"
+  ],
+  "author": "kitepon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitepon-rgb/Throughline.git"
+  },
+  "bin": {
+    "throughline": "bin/throughline.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test src/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22.5"
+  }
+}

package/src/cli/doctor.mjs

@@ -0,0 +1,98 @@
+/**
+ * throughline doctor — 環境チェック
+ *
+ * チェック項目:
+ *   - Node.js バージョン >= 22.5
+ *   - node:sqlite が使えるか
+ *   - ~/.throughline/throughline.db が書き込み可能か
+ *   - ~/.claude/settings.json に Throughline hook が登録されているか
+ */
+
+import { existsSync, accessSync, readFileSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+const GREEN = '\x1b[32m✓\x1b[0m';
+const RED = '\x1b[31m✗\x1b[0m';
+const YELLOW = '\x1b[33m!\x1b[0m';
+
+async function check(label, fn) {
+  try {
+    const result = await fn();
+    if (result === false) {
+      console.log(`${YELLOW} ${label}`);
+    } else {
+      console.log(`${GREEN} ${label}${result ? ': ' + result : ''}`);
+    }
+    return true;
+  } catch (err) {
+    console.log(`${RED} ${label}: ${err.message}`);
+    return false;
+  }
+}
+
+export async function run() {
+  console.log('throughline doctor\n');
+
+  // Node.js バージョン
+  await check('Node.js >= 22.5', () => {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 22 || (major === 22 && minor < 5)) {
+      throw new Error(`Node.js ${process.versions.node} — 22.5 以上が必要`);
+    }
+    return process.versions.node;
+  });
+
+  // node:sqlite
+  await check('node:sqlite が使えるか', async () => {
+    const { DatabaseSync } = await import('node:sqlite');
+    new DatabaseSync(':memory:').close();
+    return 'ok';
+  });
+
+  // DB ディレクトリ
+  const dbDir = join(homedir(), '.throughline');
+  const dbPath = join(dbDir, 'throughline.db');
+  await check('~/.throughline/ ディレクトリ', () => {
+    if (!existsSync(dbDir)) throw new Error('ディレクトリが存在しない（初回実行前）');
+    accessSync(dbDir, constants.W_OK);
+    return dbDir;
+  });
+
+  // DB ファイル
+  await check('throughline.db', () => {
+    if (!existsSync(dbPath)) return false; // 未作成（初回前）
+    accessSync(dbPath, constants.W_OK);
+    return dbPath;
+  });
+
+  // hook 登録確認（グローバルまたはプロジェクトローカル）
+  const globalSettings = join(homedir(), '.claude', 'settings.json');
+  const localSettings = join(process.cwd(), '.claude', 'settings.json');
+  await check('Throughline hook が登録されているか', () => {
+    function hasHook(filePath) {
+      if (!existsSync(filePath)) return false;
+      const settings = JSON.parse(readFileSync(filePath, 'utf8'));
+      return Object.values(settings.hooks ?? {}).flat().some(group =>
+        (group.hooks ?? []).some(h => h.command?.includes('throughline'))
+      );
+    }
+    if (hasHook(globalSettings)) return 'グローバル (~/.claude/settings.json)';
+    if (hasHook(localSettings)) return 'プロジェクトローカル (.claude/settings.json)';
+    throw new Error('登録なし — throughline install を実行してください');
+  });
+
+  // PATH 上に throughline があるか
+  await check('throughline コマンドが PATH で見つかるか', () => {
+    try {
+      const which = process.platform === 'win32' ? 'where throughline' : 'which throughline';
+      const result = execSync(which, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      return result.split(/\r?\n/)[0];
+    } catch {
+      throw new Error('見つからない — npm install -g throughline を実行してください');
+    }
+  });
+
+  console.log('');
+}

package/src/cli/install.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * throughline install / uninstall
+ *
+ * デフォルト: ~/.claude/settings.json（グローバル、全プロジェクトに適用）
+ * --project : .claude/settings.json（プロジェクトローカル）
+ * --uninstall: hook を削除
+ *
+ * 登録コマンドは PATH 解決型 (throughline <subcommand>) を使う。
+ * node のインストール先や OS が変わっても PATH さえ通れば動く。
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+// Throughline が管理する hook コマンド一覧
+// schema v4 以降: PostToolUse (capture-tool) は廃止。Stop 内で L2/L3 を一括処理する。
+const SC_COMMANDS = [
+  'throughline process-turn',
+  'throughline session-start',
+  // 旧コマンド（アンインストール時に除去する）
+  'throughline inject-context',
+  'throughline capture-tool',
+  'node src/detail-capture.mjs',
+  'node src/classifier.mjs',
+  'node src/turn-processor.mjs',
+  'node src/context-injector.mjs',
+];
+
+const SC_HOOKS = {
+  SessionStart: {
+    hooks: [{ type: 'command', command: 'throughline session-start' }],
+  },
+  Stop: {
+    hooks: [{ type: 'command', command: 'throughline process-turn' }],
+  },
+};
+
+function resolveSettingsPath(args) {
+  if (args.includes('--project')) {
+    return join(process.cwd(), '.claude', 'settings.json');
+  }
+  return join(homedir(), '.claude', 'settings.json');
+}
+
+function readSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return {};
+  return JSON.parse(readFileSync(settingsPath, 'utf8'));
+}
+
+function writeSettings(settingsPath, obj) {
+  const dir = dirname(settingsPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(obj, null, 2) + '\n');
+}
+
+export async function run(args = []) {
+  const uninstall = args.includes('--uninstall');
+  const settingsPath = resolveSettingsPath(args);
+  const current = readSettings(settingsPath);
+  const existingHooks = current.hooks ?? {};
+  const scSet = new Set(SC_COMMANDS);
+
+  if (uninstall) {
+    for (const [key, groups] of Object.entries(existingHooks)) {
+      existingHooks[key] = groups.filter(group =>
+        !(group.hooks ?? []).some(h => scSet.has(h.command))
+      );
+      if (existingHooks[key].length === 0) delete existingHooks[key];
+    }
+
+    if (Object.keys(existingHooks).length === 0) {
+      delete current.hooks;
+    } else {
+      current.hooks = existingHooks;
+    }
+
+    writeSettings(settingsPath, current);
+    console.log('Throughline hooks を削除しました。');
+    console.log(`  ${settingsPath}`);
+    return;
+  }
+
+  // インストール
+  for (const [key, entry] of Object.entries(SC_HOOKS)) {
+    const list = existingHooks[key] ?? [];
+    const cmd = entry.hooks[0].command;
+    const alreadyExists = list.some(group =>
+      (group.hooks ?? []).some(h => h.command === cmd)
+    );
+    if (!alreadyExists) {
+      existingHooks[key] = [entry, ...list];
+    }
+  }
+
+  current.hooks = existingHooks;
+  writeSettings(settingsPath, current);
+
+  const scope = args.includes('--project') ? 'プロジェクトローカル' : 'グローバル（全プロジェクト）';
+  console.log(`Throughline hooks をインストールしました [${scope}]`);
+  console.log(`  ${settingsPath}`);
+  console.log('');
+  console.log('有効な hooks:');
+  console.log('  SessionStart → throughline session-start  (セッション記録・記憶張り替え・L1/L2 注入)');
+  console.log('  Stop         → throughline process-turn   (L1 要約 + L2 本文保存 + L3 詳細保存)');
+  console.log('');
+  console.log('  アンインストール: throughline uninstall');
+}