@scrylog/cli 0.1.0

package/src/daemon/collectors/claude/hooks.ts

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SessionModel, SessionState } from "../../../shared/types";
+import type { ClaudeSessionMeta } from "../../../shared/types";
+
+export interface ClaudeHookFileData {
+  eventType?: string;
+  eventTime?: number;
+  hookSeq?: number;
+  state?: SessionState;
+  hasAttention?: boolean;
+  attentionKind?: "permission" | "question" | "turn" | "none";
+  summary?: string;
+  activeTool?: string;
+  toolName?: string;
+  toolInputSummary?: string;
+  toolResultStatus?: "started" | "completed" | "error" | "blocked" | "denied" | "unknown";
+  permissionMode?: string;
+  startSource?: string;
+  endReason?: string;
+  errorType?: string;
+  agentId?: string;
+  agentType?: string;
+  transcriptPath?: string;
+  currentPath?: string;
+  lastActivity?: number;
+  parentSessionId?: string;
+  detectionSource?: "claude-hook";
+}
+
+export function hasClaudePermissionPrompt(sample: SessionModel["sample"] | null | undefined): boolean {
+  if (!sample) return false;
+  return /Do you want to proceed\?/i.test(sample.lines.join("\n"));
+}
+
+export function isValidHookData(data: ClaudeHookFileData): boolean {
+  return typeof data.eventType === "string"
+    && data.eventType.length > 0
+    && typeof data.eventTime === "number"
+    && Number.isFinite(data.eventTime)
+    && typeof data.hookSeq === "number"
+    && Number.isFinite(data.hookSeq)
+    && data.state !== undefined
+    && typeof data.hasAttention === "boolean"
+    && typeof data.attentionKind === "string";
+}
+
+export function readHookData(hooksDir: string, sessionId: string): Partial<SessionModel> | null {
+  if (!existsSync(hooksDir)) return null;
+  const hookFile = join(hooksDir, `${sessionId}.json`);
+  if (!existsSync(hookFile)) return null;
+  try {
+    const raw = readFileSync(hookFile, "utf8");
+    const data = JSON.parse(raw) as ClaudeHookFileData;
+    if (!isValidHookData(data)) return null;
+    return {
+      ...(data.state !== undefined ? { state: data.state } : {}),
+      ...(data.hasAttention !== undefined ? { hasAttention: data.hasAttention } : {}),
+      ...(data.summary !== undefined ? { summary: data.summary } : {}),
+      ...(data.activeTool !== undefined ? { activeTool: data.activeTool } : {}),
+      ...(data.currentPath !== undefined ? { currentPath: data.currentPath } : {}),
+      ...(data.lastActivity !== undefined ? { lastActivity: data.lastActivity } : {}),
+      ...(data.parentSessionId !== undefined ? { parentSessionId: data.parentSessionId } : {}),
+      ...(data.detectionSource !== undefined ? { detectionSource: data.detectionSource } : {}),
+      claude: {
+        sessionId,
+        transcriptPath: data.transcriptPath ?? "",
+        ...(data.eventType !== undefined ? { hookEventType: data.eventType } : {}),
+        ...(data.eventTime !== undefined ? { hookEventTime: data.eventTime } : {}),
+        ...(data.hookSeq !== undefined ? { hookSeq: data.hookSeq } : {}),
+        ...(data.permissionMode !== undefined ? { permissionMode: data.permissionMode } : {}),
+        ...(data.startSource !== undefined ? { startSource: data.startSource } : {}),
+        ...(data.endReason !== undefined ? { endReason: data.endReason } : {}),
+        ...(data.errorType !== undefined ? { errorType: data.errorType } : {}),
+        ...(data.attentionKind !== undefined ? { attentionKind: data.attentionKind } : {}),
+        ...(data.toolName !== undefined ? { toolName: data.toolName } : {}),
+        ...(data.toolInputSummary !== undefined ? { toolInputSummary: data.toolInputSummary } : {}),
+        ...(data.toolResultStatus !== undefined ? { toolResultStatus: data.toolResultStatus } : {}),
+        ...(data.agentId !== undefined ? { agentId: data.agentId } : {}),
+        ...(data.agentType !== undefined ? { agentType: data.agentType } : {}),
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function isHookNewer(existing: SessionModel | undefined, hookData: Partial<SessionModel>): boolean {
+  const incomingSeq = hookData.claude?.hookSeq;
+  const existingSeq = existing?.claude?.hookSeq;
+  if (typeof incomingSeq === "number" && typeof existingSeq === "number") {
+    return incomingSeq >= existingSeq;
+  }
+
+  const incomingTime = hookData.claude?.hookEventTime ?? hookData.lastActivity ?? 0;
+  const existingTime = existing?.claude?.hookEventTime ?? existing?.lastActivity ?? 0;
+  return incomingTime >= existingTime;
+}
+
+export function getHookTime(session: Partial<SessionModel> | undefined): number {
+  return session?.claude?.hookEventTime ?? session?.lastActivity ?? 0;
+}
+
+export function getExistingHookData(existing: SessionModel | undefined): Partial<SessionModel> | null {
+  if (!existing) return null;
+  if (existing.detectionSource !== "claude-hook") return null;
+  if (!existing.claude?.hookEventType || typeof existing.claude.hookEventTime !== "number" || typeof existing.claude.hookSeq !== "number") {
+    return null;
+  }
+
+  return {
+    state: existing.state,
+    hasAttention: existing.hasAttention,
+    summary: existing.summary,
+    activeTool: existing.activeTool,
+    currentPath: existing.currentPath,
+    lastActivity: existing.lastActivity,
+    parentSessionId: existing.parentSessionId,
+    detectionSource: "claude-hook",
+    claude: {
+      sessionId: existing.claude.sessionId,
+      transcriptPath: existing.claude.transcriptPath,
+      hookEventType: existing.claude.hookEventType,
+      hookEventTime: existing.claude.hookEventTime,
+      hookSeq: existing.claude.hookSeq,
+      ...(existing.claude.permissionMode ? { permissionMode: existing.claude.permissionMode } : {}),
+      ...(existing.claude.startSource ? { startSource: existing.claude.startSource } : {}),
+      ...(existing.claude.endReason ? { endReason: existing.claude.endReason } : {}),
+      ...(existing.claude.errorType ? { errorType: existing.claude.errorType } : {}),
+      ...(existing.claude.attentionKind ? { attentionKind: existing.claude.attentionKind } : {}),
+      ...(existing.claude.toolName ? { toolName: existing.claude.toolName } : {}),
+      ...(existing.claude.toolInputSummary ? { toolInputSummary: existing.claude.toolInputSummary } : {}),
+      ...(existing.claude.toolResultStatus ? { toolResultStatus: existing.claude.toolResultStatus } : {}),
+      ...(existing.claude.agentId ? { agentId: existing.claude.agentId } : {}),
+      ...(existing.claude.agentType ? { agentType: existing.claude.agentType } : {}),
+    },
+  };
+}
+
+const MERGEABLE_FIELDS: (keyof ClaudeSessionMeta)[] = [
+  "hookEventType", "hookEventTime", "hookSeq",
+  "permissionMode", "startSource", "endReason", "errorType",
+  "attentionKind", "toolName", "toolInputSummary",
+  "toolResultStatus", "agentId", "agentType",
+];
+
+export function mergeClaudeMeta(
+  base: ClaudeSessionMeta,
+  incoming: Partial<ClaudeSessionMeta>,
+): ClaudeSessionMeta {
+  const result = { ...base };
+  for (const key of MERGEABLE_FIELDS) {
+    if (incoming[key] !== undefined) {
+      (result as Record<string, unknown>)[key] = incoming[key];
+    }
+  }
+  return result;
+}
+
+export function mergeHookIntoModel(model: SessionModel, hookData: Partial<SessionModel>, transcriptPath: string): SessionModel {
+  const hookClaude = hookData.claude ?? { sessionId: model.claude?.sessionId ?? model.id.replace(/^claude:/, ""), transcriptPath };
+  return {
+    ...model,
+    ...hookData,
+    state: (hookData.state as SessionState | undefined) ?? model.state,
+    hasAttention: hookData.hasAttention ?? model.hasAttention,
+    id: model.id,
+    source: model.source,
+    summary: hookData.summary ?? model.summary,
+    lastActivity: typeof hookData.lastActivity === "number" ? hookData.lastActivity : model.lastActivity,
+    activeTool: hookData.activeTool ?? model.activeTool,
+    detectionSource: "claude-hook",
+    claude: mergeClaudeMeta(
+      {
+        sessionId: hookClaude.sessionId ?? model.claude?.sessionId ?? model.id.replace(/^claude:/, ""),
+        transcriptPath: hookClaude.transcriptPath || transcriptPath,
+      },
+      hookClaude,
+    ),
+  };
+}

package/src/daemon/collectors/claude/index.ts

@@ -0,0 +1,8 @@
+export { ClaudeCollector } from "./collector";
+export type { ClaudeHookFileData } from "./hooks";
+
+// Test-accessible pure functions (not part of collector public API,
+// but exported for direct unit testing without replicating logic)
+export { inferState, extractSummary, extractTitle, isLocalCommandTranscript } from "./transcript";
+export { decodeClaudeProjectSlug } from "./discovery";
+export { mergeClaudeMeta } from "./hooks";

package/src/daemon/collectors/claude/jsonl.ts

@@ -0,0 +1,85 @@
+import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+
+export interface JsonlEntry {
+  type?: string;
+  role?: string;
+  content?: unknown;
+  message?: {
+    role?: string;
+    content?: unknown;
+  };
+  toolUse?: { name?: string };
+  timestamp?: string;
+}
+
+export interface ContentBlock {
+  type?: string;
+  text?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+}
+
+export function parseJsonlFile(path: string, maxBytes?: number): JsonlEntry[] {
+  try {
+    const content = readTextTail(path, maxBytes);
+    return parseJsonlContent(content);
+  } catch {
+    return [];
+  }
+}
+
+export function parseJsonlHead(path: string, maxBytes: number): JsonlEntry[] {
+  try {
+    return parseJsonlContent(readTextHead(path, maxBytes));
+  } catch {
+    return [];
+  }
+}
+
+export function parseJsonlContent(content: string): JsonlEntry[] {
+  return content
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as JsonlEntry;
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry): entry is JsonlEntry => entry !== null);
+}
+
+export function readTextHead(path: string, maxBytes: number): string {
+  const stat = statSync(path);
+  if (stat.size <= maxBytes) return readFileSync(path, "utf8");
+
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(maxBytes);
+    readSync(fd, buffer, 0, maxBytes, 0);
+    const text = buffer.toString("utf8");
+    const lastNewline = text.lastIndexOf("\n");
+    return lastNewline >= 0 ? text.slice(0, lastNewline) : text;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function readTextTail(path: string, maxBytes?: number): string {
+  if (!maxBytes || maxBytes <= 0) return readFileSync(path, "utf8");
+  const stat = statSync(path);
+  if (stat.size <= maxBytes) return readFileSync(path, "utf8");
+
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(maxBytes);
+    readSync(fd, buffer, 0, maxBytes, stat.size - maxBytes);
+    const text = buffer.toString("utf8");
+    const firstNewline = text.indexOf("\n");
+    return firstNewline >= 0 ? text.slice(firstNewline + 1) : text;
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/daemon/collectors/claude/transcript.ts

@@ -0,0 +1,246 @@
+import type { SessionModel, SessionState } from "../../../shared/types";
+import type { JsonlEntry, ContentBlock } from "./jsonl";
+
+export function getRole(entry: JsonlEntry): string | undefined {
+  return entry.role ?? entry.message?.role;
+}
+
+export function getBlocks(entry: JsonlEntry): ContentBlock[] {
+  const content = entry.content ?? entry.message?.content;
+  if (!Array.isArray(content)) return [];
+  return content.filter((block): block is ContentBlock => typeof block === "object" && block !== null);
+}
+
+export function getTextBlocks(entry: JsonlEntry): string[] {
+  return getBlocks(entry)
+    .filter((block) => block.type === "text" && typeof block.text === "string")
+    .map((block) => block.text!.trim())
+    .filter((text) => text.length > 0);
+}
+
+export function normalizeText(text: string): string {
+  return text
+    .replace(/<local-command-caveat>[\s\S]*?<\/local-command-caveat>/g, "")
+    .replace(/<command-name>(.*?)<\/command-name>/g, "$1")
+    .trim();
+}
+
+export function isQuestionText(text: string): boolean {
+  const trimmed = normalizeText(text);
+  return /[?]/.test(trimmed) || /^(would you|do you|can you|should i|which|what|how|please confirm|shall i|want me to)/i.test(trimmed);
+}
+
+export function isInterruptedRequestText(text: string): boolean {
+  return /^\[Request interrupted by user(?: for tool use)?\]$/i.test(text.trim());
+}
+
+export function isSyntheticUserEntry(entry: JsonlEntry): boolean {
+  if (getRole(entry) !== "user") return false;
+  if (isToolResultOnlyEntry(entry)) return true;
+  const texts = getTextBlocks(entry).map((text) => normalizeText(text));
+  return texts.length > 0 && texts.every((text) => isInterruptedRequestText(text));
+}
+
+export function isToolResultOnlyEntry(entry: JsonlEntry): boolean {
+  const blocks = getBlocks(entry);
+  return blocks.length > 0 && blocks.every((block) => block.type === "tool_result");
+}
+
+export function isThinkingOnlyAssistantEntry(entry: JsonlEntry): boolean {
+  if (getRole(entry) !== "assistant") return false;
+  const blocks = getBlocks(entry);
+  return blocks.length > 0 && blocks.every((block) => block.type === "thinking");
+}
+
+export function findLastToolResultIndex(entries: JsonlEntry[]): number {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (isToolResultOnlyEntry(entries[i]!)) return i;
+  }
+  return -1;
+}
+
+export function findLastMeaningfulEntry(entries: JsonlEntry[]): JsonlEntry | undefined {
+  const lastToolResultIndex = findLastToolResultIndex(entries);
+
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i]!;
+    const role = getRole(entry);
+    if (role !== "user" && role !== "assistant") continue;
+    if (isThinkingOnlyAssistantEntry(entry)) continue;
+    if (isSyntheticUserEntry(entry)) continue;
+
+    if (role === "assistant") {
+      const blocks = getBlocks(entry);
+      const hasToolUse = blocks.some((block) => block.type === "tool_use");
+      const hasVisibleText = getTextBlocks(entry).length > 0;
+      if (hasToolUse && !hasVisibleText && lastToolResultIndex > i) {
+        // The most recent assistant entry is a fulfilled tool_use cycle.
+        // In agentic mode, a completed tool cycle means the agent is
+        // processing the result — return the entry so inferState sees
+        // it as "working" (assistant with tool_use, no visible text).
+        return entry;
+      }
+    }
+
+    return entry;
+  }
+
+  return undefined;
+}
+
+/** Infer session state from the last meaningful transcript turn */
+export function inferState(entries: JsonlEntry[]): SessionState {
+  if (entries.length === 0) return "idle";
+
+  const last = findLastMeaningfulEntry(entries);
+  if (!last) return "idle";
+
+  const role = getRole(last);
+  if (role === "assistant") {
+    const blocks = getBlocks(last);
+    const texts = getTextBlocks(last);
+    const hasToolUse = blocks.some((block) => block.type === "tool_use");
+
+    if (texts.some((value) => isQuestionText(value))) return "waiting-input";
+    if (texts.length > 0) return "idle";
+    if (hasToolUse) return "working";
+    return "idle";
+  }
+
+  if (role === "user") {
+    return isSyntheticUserEntry(last) ? "idle" : "working";
+  }
+
+  return "idle";
+}
+
+/** Extract a human-readable summary from the last assistant message */
+export function extractSummary(entries: JsonlEntry[]): string {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i]!;
+    const role = getRole(entry);
+    if (role !== "assistant") continue;
+    if (isThinkingOnlyAssistantEntry(entry)) continue;
+
+    const content = getBlocks(entry);
+    if (content.length === 0) continue;
+
+    for (const block of content) {
+      if (block.type === "tool_use" && block.name) {
+        const cmd = typeof block.input?.command === "string" ? `: ${block.input.command.slice(0, 60)}` : "";
+        return `Using ${block.name}${cmd}`;
+      }
+    }
+
+    for (const block of content) {
+      if (block.type === "text" && block.text) {
+        const first = normalizeText(block.text).split("\n")[0] ?? "";
+        if (first.length > 0) return first.slice(0, 120);
+      }
+    }
+  }
+
+  return "Claude session";
+}
+
+/**
+ * A transcript whose user text entries are only the initialization caveat,
+ * `/usage` slash-command invocations, or local-command stdout blocks.
+ * Generated by third-party probe tools (e.g. CodexBar's ClaudeProbe) that
+ * launch `claude` headlessly to read usage stats — not interactive work.
+ * Limited to `/usage` to avoid filtering sessions that run other slash
+ * commands as part of real work.
+ */
+export function isUsageProbeTranscript(entries: JsonlEntry[]): boolean {
+  const texts: string[] = [];
+  for (const entry of entries) {
+    if (getRole(entry) !== "user") continue;
+    const content = entry.content ?? entry.message?.content;
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (typeof block === "object" && block !== null && block.type === "text" && typeof block.text === "string") {
+          texts.push(block.text);
+        }
+      }
+    } else if (typeof content === "string") {
+      texts.push(content);
+    }
+  }
+  if (texts.length === 0) return false;
+  // Require at least one /usage slash command — a bare caveat alone is the
+  // interactive session init message, not a probe.
+  const hasUsageCommand = texts.some((text) => /<command-name>\s*\/usage[\s<]/.test(text));
+  if (!hasUsageCommand) return false;
+  return texts.every((text) =>
+    text.startsWith("<local-command-caveat>")
+    || /<command-name>\s*\/usage[\s<]/.test(text)
+    || text.startsWith("<local-command-stdout>"),
+  );
+}
+
+/**
+ * Returns true when the transcript was generated in Claude Code's local-commands
+ * mode (e.g. `claude -p "..."`).  These are headless batch runs, not interactive
+ * sessions — they clutter the TUI and carry no meaningful state.
+ */
+export function isLocalCommandTranscript(entries: JsonlEntry[]): boolean {
+  // Detect transcripts emitted by headless probe tools that only run `/usage`
+  // (e.g. CodexBar's ClaudeProbe). These look like interactive sessions to the
+  // caveat check below (bare init caveat + slash command), but carry no real
+  // work state. Checked first because the caveat loop returns early.
+  if (isUsageProbeTranscript(entries)) return true;
+
+  for (const entry of entries) {
+    const role = entry.role ?? entry.message?.role;
+    if (role !== "user") continue;
+    const content = entry.content ?? entry.message?.content;
+    let text = "";
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (typeof block === "object" && block !== null && "type" in block) {
+          const b = block as { type: string; text?: string };
+          if (b.type === "text" && typeof b.text === "string") {
+            text = b.text;
+            break;
+          }
+        }
+      }
+    } else if (typeof content === "string") {
+      text = content;
+    }
+    // Stop at first user entry regardless
+    if (!text.startsWith("<local-command-caveat>")) break;
+    // A bare caveat with no trailing task content is the initialization message
+    // Claude Code sends at the start of interactive sessions — not a headless
+    // `claude -p "task"` invocation. Real local commands have the task prompt
+    // appended after the closing tag.
+    const closingTag = "</local-command-caveat>";
+    const afterCaveat = text.slice(text.indexOf(closingTag) + closingTag.length).trim();
+    return afterCaveat.length > 0;
+  }
+  return false;
+}
+
+/** Extract a title from the first user message (the initial task/request) */
+export function extractTitle(entries: JsonlEntry[]): string | undefined {
+  for (const entry of entries) {
+    const role = getRole(entry);
+    if (role !== "user") continue;
+    if (isToolResultOnlyEntry(entry)) continue;
+
+    const content = entry.content ?? entry.message?.content;
+    if (Array.isArray(content)) {
+      for (const block of getBlocks(entry)) {
+        if (block.type === "text" && block.text) {
+          const first = normalizeText(block.text).split("\n")[0] ?? "";
+          if (first.length === 0) continue;
+          return first.slice(0, 80);
+        }
+      }
+    } else if (typeof content === "string" && content.trim().length > 0) {
+      const first = normalizeText(content).split("\n")[0] ?? "";
+      if (first.length > 0) return first.slice(0, 80);
+    }
+  }
+  return undefined;
+}

package/src/daemon/collectors/codex/README.md

@@ -0,0 +1,147 @@
+# Codex Collector
+
+This module provides session discovery and real-time state tracking for OpenAI Codex CLI.
+
+## Architecture
+
+```
+  ~/.codex/sessions/YYYY/MM/DD/*.jsonl   ~/.codex/archived_sessions/*.jsonl
+         │                                        │
+         │                                        │
+         ▼                                        ▼
+  ┌──────────────┐                          ┌──────────────┐
+  │  discovery   │  discoverTranscripts()   │    hooks     │  readHookData()
+  │              │                        │              │
+  └──────┬───────┘                        └──────┬───────┘
+         │                                        │
+         │                                        │
+         ▼                                        │
+  ┌──────────────┐                                │
+  │     jsonl    │  parseJsonlFile()              │
+  └──────┬───────┘                                │
+         │                                        │
+         ▼                                        │
+  ┌──────────────┐                                │
+  │  transcript  │  extractMeta()                │
+  │              │  (no state inference)          │
+  └──────┬───────┘                                │
+         │                                        │
+         └────────────┬───────────────────────────┘
+                      │
+                      ▼
+         ┌─────────────────────────────────┐
+         │           collector.ts            │
+         │                                 │
+         │  ┌──────────────┐  ┌──────────┐ │
+         │  │ 30s poll     │  │ fs.watch │ │
+         │  │ run()        │  │ hooksDir │ │
+         │  └──────┬───────┘  └────┬─────┘ │
+         │         │               │         │
+         │         └──────┬────────┘         │
+         │                │                  │
+         │                ▼                  │
+         │       processTranscript()         │
+         │                │                  │
+         │                │  ┌──────────────┴─────────────┐
+         │                └──│ mergeHookIntoModel()         │
+         │                   │ (if hook newer than transcript)│
+         │                   └──────────────────────────────┘
+         │                │                  │
+         │                ▼                  │
+         │       store.upsertSession()       │
+         │       store.syncChildSessionIds() │
+         └─────────────────────────────────┘
+                │
+                ▼
+        DaemonStore ──► /api/events SSE ──► TUI
+```
+
+## Modules
+
+| File | Responsibility | Key Exports |
+|------|-------------|-------------|
+| `discovery.ts` | Scan `~/.codex/sessions/YYYY/MM/DD/*.jsonl` and `~/.codex/archived_sessions/*.jsonl`; respect `$CODEX_HOME` | `discoverTranscripts()`, `getCodexDir()` |
+| `jsonl.ts` | Read JSONL tail with byte-size limits; parse lines into typed entries | `parseJsonlFile()`, `readTextTail()`, `CodexJsonlEntry` |
+| `transcript.ts` | Extract session metadata from JSONL (`session_meta`, `turn_context`, `token_count`). No state inference. | `extractMeta()`, `CodexTranscriptMeta` |
+| `hooks.ts` | Read/validate hook JSON files; merge hook data into a session model; merge codex metadata without overwriting existing fields | `readHookData()`, `mergeHookIntoModel()`, `mergeCodexMeta()`, `isHookNewer()`, `getHookTime()`, `isValidHookData()`, `CodexHookFileData` |
+| `collector.ts` | Orchestrate discovery, transcript watching, hook watching, deduplication, and store writes | `CodexCollector` (implements `Collector`) |
+| `index.ts` | Public re-exports | `CodexCollector`, `extractMeta` |
+
+## JSONL Format
+
+Codex JSONL files contain three processed line types:
+
+- `session_meta` — session identity and fork lineage
+- `turn_context` — active model slug
+- `event_msg` with `payload.type === "token_count"` — token usage
+
+No conversational content is parsed (format is unstable).
+
+## Hook Requirement
+
+Hooks are **required** for real-time state. Without hooks:
+
+- Sessions are discovered from JSONL files
+- State is always `idle`
+- `detectionSource` is `"codex-transcript"`
+
+With hooks (`codex.hooksEnabled: true`):
+
+- State is derived from Codex lifecycle events (`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, `Stop`)
+- `detectionSource` is `"codex-hook"`
+- `turn_id` is captured for turn-level tracking
+
+## Install Hooks
+
+```bash
+scrylog codex hooks install
+```
+
+This writes `~/.codex/hooks.json` with entries for all 6 Codex hook events pointing to `scrylog-codex-hook`.
+
+## Hook Merge Priority
+
+When both transcript and hook data exist, the collector uses this priority:
+
+1. **Hook newer** (`hookSeq` or `hookEventTime` >= existing): hook data wins for `state`, `hasAttention`, `summary`, `activeTool`
+2. **Hook older**: transcript data wins (except `codex` metadata merged via `mergeCodexMeta`)
+3. **Hook-managed session** (`detectionSource === "codex-hook"`): transcript can only fill missing metadata (e.g. `transcriptPath`), never override state
+
+## State Derivation Rules
+
+| Event | State | Reason |
+|-------|-------|--------|
+| `SessionStart` | `idle` | Session just started |
+| `UserPromptSubmit` | `working` | User submitted a prompt, Codex is working |
+| `PreToolUse` | `working` | Codex is about to use a tool |
+| `PermissionRequest` | `waiting-input` | Codex is waiting for user permission |
+| `PostToolUse` | `working` | Tool completed, Codex continues |
+| `Stop` with `stop_hook_active: true` | `working` | Codex will continue automatically |
+| `Stop` with `stop_hook_active: false` | `idle` | Session ended |
+
+## Configuration
+
+```json
+{
+  "codex": {
+    "codexDir": "/path/to/.codex",
+    "hooksEnabled": true,
+    "hooksDir": "/tmp/scrylog-codex-hooks"
+  }
+}
+```
+
+## Interactions
+
+| Component | How |
+|-----------|-----|
+| `GitCollector` | Resolves `currentPath` → `project` when hooks/transcript provide a directory |
+| `DaemonStore` | Upserts sessions; clears old bindings via `syncChildSessionIds()` |
+| `TmuxCollector` | Reads `@codex-session` pane option for authoritative pane→session linking |
+| `Scheduler` | Calls `start()` → sets up `30s` discovery interval + `5s` fallback re-read |
+| `TUI` | Receives updates via SSE from the store |
+
+## Detection Sources Produced
+
+- `"codex-transcript"` — session discovered from `.jsonl` file, state is `idle`
+- `"codex-hook"` — session discovered/enriched from hook JSON, state is authoritative from Codex CLI directly