oh-my-claudecode 0.2.3 → 0.2.4

package/README.md

@@ -144,6 +144,53 @@ Named for the Great Race of Yith from *The Shadow Out of Time* — mind-transfer
 - **Crash-safe work-packet flows** — pending continuations for LLM-requiring operations persist to the same store and survive server restarts; resuming with the same continuation token picks up where the flow left off.
 - **Replaces Claude Code's built-in auto-memory** via the `memory-override` SessionStart hook, which tells the session not to write to the built-in memory files. Disable the override with `disabled_hooks: ["memory-override"]` if you prefer to keep the built-in system active.
 
+### The binding ritual (`oh-my-claudecode bind`)
+
+Fresh installs start with an empty `necronomicon.json`. To populate it
+with history, run one command in your terminal:
+
+```bash
+oh-my-claudecode bind
+```
+
+This kicks off a six-phase ritual with a real ANSI TUI (progress bars,
+section headers, per-phase status):
+
+1. **Embedding sigil** — downloads the local nomic embedding model
+   (~137 MB) with a live byte-counter progress bar.
+2. **Claude Code transcripts** — scans every subdirectory under
+   `~/.claude/projects/` (every project you've ever opened a session
+   in), parses the `.jsonl` transcripts, and writes one raw
+   observation per user prompt / assistant text / tool call.
+3. **Opencode grimoire** — if you're migrating from oh-my-opencode, the
+   ritual auto-detects `~/.local/share/opencode/opencode.db` and
+   imports every project / session / message / part it finds.
+4. **Sisyphus migration** — walks your home looking for legacy
+   `.sisyphus/` directories (the oh-my-opencode equivalent of
+   `.elder-gods/`) and copies plans, handoffs, and evidence into the
+   new layout without touching the source.
+5. **Project code scan** — for each project the CLI has seen, walks
+   the code tree (gitignore-aware) and seeds preliminary memories:
+   language stats, package metadata, README sections, directory tree.
+6. **Sealing** — reports how many raw observations are queued for
+   compression and points you at the next step.
+
+The ritual is **resumable**: if any phase errors or you interrupt it,
+re-running `oh-my-claudecode bind` picks up from the failed phase via
+the `KV.bindState` cursor — no manual intervention required.
+
+Phase 2 (LLM-dependent compression of raw observations into
+searchable memories) runs **inside a Claude Code session** via the
+work-packet loop. Either:
+
+- Open Claude Code and run `/necronomicon-bind` — uses your
+  subscription auth via the MCP work-packet protocol.
+- Or install a cron entry that spawns `claude -p` on an interval:
+  ```bash
+  oh-my-claudecode bind --install-cron --interval 1h
+  ```
+  The cron tick drives compression unattended. No API key needed.
+
 ### Work-packet protocol — LLM ops without an API key
 
 13 of Yith's memory operations need an LLM to do their work (`crystallize`, `consolidate`, `consolidate-pipeline`, `compress`, `summarize`, `flow-compress`, `graph-extract`, `temporal-graph-extract`, `expand-query`, `skill-extract`, `reflect`, `enrich-window`, `enrich-session`). If Yith has its own `ANTHROPIC_API_KEY` in `~/.oh-my-claudecode/yith/.env`, these run directly in-process.
@@ -233,7 +280,7 @@ After installation these are available in Claude Code sessions:
 | Command | Description |
 |---------|-------------|
 | `/cthulhu` | Activate Cthulhu orchestrator mode (also creates `.elder-gods/` on first use) |
-| `/bind-necronomicon` | First-time Yith Archive setup ritual — tome check, embedding warmup, search verify, optional session backfill |
+| `/necronomicon-bind` | Necronomicon binding ritual — shells out to `oh-my-claudecode bind` (real TUI, all-projects ingestion, opencode import, sisyphus migration, preliminary code scan) then drains pending compression via the work-packet loop using this session's LLM |
 | `/shoggoth` | Fast parallel codebase search |
 | `/yog-sothoth` | Consult the architecture/debug advisor |
 | `/elder-loop` | Start the self-referential completion loop |

package/dist/cli/bind-cron.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cron installer + `claude -p` spawn-command assembly for unattended
+ * Necronomicon bind / compression.
+ *
+ * Everything here is a pure function over strings — no process
+ * spawning, no crontab mutation, no fs writes. The CLI entry point
+ * orchestrates the actual `crontab -l` / `crontab -` dance; this
+ * module only handles the string-level logic so tests can verify
+ * every edge case without side effects.
+ *
+ * The cron entry calls `oh-my-claudecode bind --resume`, which:
+ *   1. Runs any pending Phase 1 work (filesystem ingestion — no LLM).
+ *   2. For Phase 2 (compression), if an ANTHROPIC_API_KEY is
+ *      configured, routes directly through the in-process LLM
+ *      provider. Otherwise spawns `claude -p` with the command
+ *      produced by `buildClaudePSpawnCommand` below, so Claude Code's
+ *      own subscription auth drives the work-packet loop.
+ */
+/** Suffix appended to every bind-installed crontab entry so the
+ *  installer can find + replace its own line without clobbering
+ *  unrelated entries. */
+export declare const BIND_CRON_MARKER = "# oh-my-claudecode bind";
+/**
+ * Convert a short interval spec like `"1h"`, `"30m"`, `"1d"` into a
+ * cron schedule string. Accepts:
+ *
+ *   `Nm`  — every N minutes (N > 0)
+ *   `Nh`  — every N hours   (N > 0)
+ *   `Nd`  — every N days    (currently supports 1d; multi-day uses
+ *           "at midnight every day" since cron doesn't natively
+ *           express "every 2 days" without a workaround)
+ *   `N`   — bare number, interpreted as minutes
+ *
+ * Throws on malformed input or zero/negative intervals so the CLI
+ * can surface a clear error.
+ */
+export declare function parseIntervalSpec(spec: string): string;
+export interface ClaudePSpawnOptions {
+    /** Observations per compress-batch-step call. Default 100. */
+    limit?: number;
+    /** Dollar cap on the claude -p invocation. Default 2.00. */
+    maxBudgetUsd?: number;
+    /** Model alias. Default "sonnet" — fast and cheap for compression. */
+    model?: string;
+    /** Where to write the claude -p log. Default /dev/null. */
+    logPath?: string;
+}
+/**
+ * Assemble the shell command that a cron tick runs to drive Phase 2
+ * compression via `claude -p`. The command is a single string suitable
+ * for a crontab line or a shell -c invocation.
+ *
+ * Security contract: --allowedTools restricts the spawn to the yith
+ * MCP tools only, so a runaway prompt can't shell out / edit files /
+ * read arbitrary code. --max-budget-usd caps the total API spend per
+ * tick. --permission-mode auto skips interactive prompts.
+ *
+ * The embedded prompt tells the spawned Claude to call
+ * mem::compress-batch-step in a loop via the work-packet protocol,
+ * terminating when the response is {status: "success"} or after 20
+ * rounds (safety cap).
+ */
+export declare function buildClaudePSpawnCommand(opts?: ClaudePSpawnOptions): string;
+export interface CrontabLineOptions {
+    /** 5-field cron schedule string, e.g. `0 * * * *`. */
+    schedule: string;
+    /** Command to run on each tick. */
+    command: string;
+}
+/**
+ * Build a full crontab line including the installer marker. The marker
+ * is a trailing comment so the line looks like a normal cron entry to
+ * operators who inspect their crontab.
+ */
+export declare function buildCrontabLine(opts: CrontabLineOptions): string;
+/**
+ * Merge `newLine` into an existing crontab file body, replacing any
+ * previous bind entry (identified by BIND_CRON_MARKER) in place. If
+ * no previous entry exists, appends. Preserves all other lines
+ * unchanged — including comments, whitespace, and unrelated jobs.
+ *
+ * Returns the updated crontab body as a string. Callers pipe this
+ * to `crontab -` to commit.
+ */
+export declare function installCrontabEntry(existing: string, newLine: string): string;
+//# sourceMappingURL=bind-cron.d.ts.map

package/dist/cli/bind-cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-cron.d.ts","sourceRoot":"","sources":["../../src/cli/bind-cron.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;yBAEyB;AACzB,eAAO,MAAM,gBAAgB,4BAA4B,CAAA;AAMzD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiCtD;AAMD,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,mBAAwB,GAC7B,MAAM,CA0BR;AAYD,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAA;IAChB,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAEjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,MAAM,CA8BR"}

package/dist/cli/bind-cron.js

@@ -0,0 +1,161 @@
+/**
+ * Cron installer + `claude -p` spawn-command assembly for unattended
+ * Necronomicon bind / compression.
+ *
+ * Everything here is a pure function over strings — no process
+ * spawning, no crontab mutation, no fs writes. The CLI entry point
+ * orchestrates the actual `crontab -l` / `crontab -` dance; this
+ * module only handles the string-level logic so tests can verify
+ * every edge case without side effects.
+ *
+ * The cron entry calls `oh-my-claudecode bind --resume`, which:
+ *   1. Runs any pending Phase 1 work (filesystem ingestion — no LLM).
+ *   2. For Phase 2 (compression), if an ANTHROPIC_API_KEY is
+ *      configured, routes directly through the in-process LLM
+ *      provider. Otherwise spawns `claude -p` with the command
+ *      produced by `buildClaudePSpawnCommand` below, so Claude Code's
+ *      own subscription auth drives the work-packet loop.
+ */
+/** Suffix appended to every bind-installed crontab entry so the
+ *  installer can find + replace its own line without clobbering
+ *  unrelated entries. */
+export const BIND_CRON_MARKER = "# oh-my-claudecode bind";
+// ============================================================================
+// Interval spec parser
+// ============================================================================
+/**
+ * Convert a short interval spec like `"1h"`, `"30m"`, `"1d"` into a
+ * cron schedule string. Accepts:
+ *
+ *   `Nm`  — every N minutes (N > 0)
+ *   `Nh`  — every N hours   (N > 0)
+ *   `Nd`  — every N days    (currently supports 1d; multi-day uses
+ *           "at midnight every day" since cron doesn't natively
+ *           express "every 2 days" without a workaround)
+ *   `N`   — bare number, interpreted as minutes
+ *
+ * Throws on malformed input or zero/negative intervals so the CLI
+ * can surface a clear error.
+ */
+export function parseIntervalSpec(spec) {
+    if (!spec)
+        throw new Error("parseIntervalSpec: empty interval");
+    const m = spec.match(/^(\d+)([mhd])?$/);
+    if (!m) {
+        throw new Error(`parseIntervalSpec: invalid interval "${spec}" — use Nm / Nh / Nd`);
+    }
+    const n = parseInt(m[1], 10);
+    const unit = m[2] ?? "m";
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`parseIntervalSpec: interval must be > 0 (got ${n})`);
+    }
+    if (unit === "m") {
+        // Every N minutes. If N divides 60 evenly, use step syntax.
+        if (n >= 60 && n % 60 === 0) {
+            const hours = n / 60;
+            return hours === 1 ? "0 * * * *" : `0 */${hours} * * *`;
+        }
+        return `*/${n} * * * *`;
+    }
+    if (unit === "h") {
+        return n === 1 ? "0 * * * *" : `0 */${n} * * *`;
+    }
+    // Days: run at midnight every N days. Cron doesn't natively support
+    // "every 2 days" so we emit the 1d form only.
+    if (n === 1)
+        return "0 0 * * *";
+    // Fall back to "every N-th day of month" — not perfect but better
+    // than refusing the input.
+    return `0 0 */${n} * *`;
+}
+/**
+ * Assemble the shell command that a cron tick runs to drive Phase 2
+ * compression via `claude -p`. The command is a single string suitable
+ * for a crontab line or a shell -c invocation.
+ *
+ * Security contract: --allowedTools restricts the spawn to the yith
+ * MCP tools only, so a runaway prompt can't shell out / edit files /
+ * read arbitrary code. --max-budget-usd caps the total API spend per
+ * tick. --permission-mode auto skips interactive prompts.
+ *
+ * The embedded prompt tells the spawned Claude to call
+ * mem::compress-batch-step in a loop via the work-packet protocol,
+ * terminating when the response is {status: "success"} or after 20
+ * rounds (safety cap).
+ */
+export function buildClaudePSpawnCommand(opts = {}) {
+    const limit = opts.limit ?? 100;
+    const maxBudgetUsd = opts.maxBudgetUsd ?? 2.0;
+    const model = opts.model ?? "sonnet";
+    const logPath = opts.logPath ?? "/dev/null";
+    const prompt = `Call yith_trigger with name "mem::compress-batch-step" and args {"limit": ${limit}}. ` +
+        `If the response has status "needs_llm_work", execute each packet's prompts ` +
+        `(read the systemPrompt + userPrompt, produce the compression XML the system ` +
+        `prompt asks for), then call yith_commit_work with the continuation token and ` +
+        `an array of {id, completion} results. Repeat this loop until the response is ` +
+        `{status: "success"} or you've processed 20 batches total. Output a single-line ` +
+        `JSON summary {"compressed": N, "failed": N, "errors": []} and exit.`;
+    return [
+        `claude`,
+        `--print`,
+        `--permission-mode auto`,
+        `--max-budget-usd ${maxBudgetUsd}`,
+        `--model ${model}`,
+        `--allowedTools "mcp__yith-archive__yith_trigger,mcp__yith-archive__yith_commit_work"`,
+        `--output-format json`,
+        `${shellEscapeSingle(prompt)}`,
+        `>> ${logPath} 2>&1`,
+    ].join(" ");
+}
+function shellEscapeSingle(s) {
+    // Wrap in single quotes and escape any literal single quote the
+    // shell-safe way: '...''...'...
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Build a full crontab line including the installer marker. The marker
+ * is a trailing comment so the line looks like a normal cron entry to
+ * operators who inspect their crontab.
+ */
+export function buildCrontabLine(opts) {
+    return `${opts.schedule} ${opts.command} ${BIND_CRON_MARKER}`;
+}
+/**
+ * Merge `newLine` into an existing crontab file body, replacing any
+ * previous bind entry (identified by BIND_CRON_MARKER) in place. If
+ * no previous entry exists, appends. Preserves all other lines
+ * unchanged — including comments, whitespace, and unrelated jobs.
+ *
+ * Returns the updated crontab body as a string. Callers pipe this
+ * to `crontab -` to commit.
+ */
+export function installCrontabEntry(existing, newLine) {
+    const lines = existing.split("\n");
+    const out = [];
+    let replaced = false;
+    for (const line of lines) {
+        if (line.includes(BIND_CRON_MARKER)) {
+            if (!replaced) {
+                out.push(newLine);
+                replaced = true;
+            }
+            // Drop duplicate bind entries.
+            continue;
+        }
+        out.push(line);
+    }
+    if (!replaced) {
+        // Make sure we don't leave a trailing empty line + the new entry
+        // mashed together. Trim trailing blank lines before appending.
+        while (out.length > 0 && out[out.length - 1] === "") {
+            out.pop();
+        }
+        out.push(newLine);
+    }
+    // Ensure trailing newline — crontabs want it.
+    let body = out.join("\n");
+    if (!body.endsWith("\n"))
+        body += "\n";
+    return body;
+}
+//# sourceMappingURL=bind-cron.js.map

package/dist/cli/bind-cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-cron.js","sourceRoot":"","sources":["../../src/cli/bind-cron.ts"],"names":[],"mappings":"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"}

package/dist/cli/bind.d.ts

@@ -0,0 +1,78 @@
+/**
+ * oh-my-claudecode bind — the CLI subcommand that drives the
+ * Necronomicon binding ritual.
+ *
+ * Architecture: a state-machine runner (`runBind`) reads `KV.bindState`,
+ * walks through each phase in `BIND_PHASE_ORDER`, invokes the matching
+ * `PhaseRunner`, and persists progress after every transition. Phases
+ * are injectable — tests pass fakes; production passes the real
+ * runners defined in `defaultPhaseRunners()`.
+ *
+ * Failure semantics: if any phase throws, `runBind` records the error
+ * into bindState, halts (does NOT run subsequent phases), and returns.
+ * The CLI entry point surfaces the error via the TUI and exits with
+ * a non-zero code. A re-run picks up from the failed phase and retries
+ * it — the state machine treats `failed` the same as `pending`.
+ *
+ * Cron-friendly: the same entry point is called from `bind --resume`
+ * which prints to stdout and exits, so a crontab can invoke it on
+ * an interval without an interactive session.
+ */
+import type { YithArchiveHandle } from "../features/yith-archive/index.js";
+import { type BindPhase, type BindState } from "../features/yith-archive/state/bind-state.js";
+import { TuiWriter } from "./tui.js";
+export interface BindContext {
+    archive: YithArchiveHandle;
+    tui: TuiWriter;
+}
+export interface PhaseRunner {
+    name: BindPhase;
+    /**
+     * Execute the phase's work. Return a details object to merge into
+     * the phase's `details` field (e.g., per-project counts, cursor
+     * positions). Throw on failure — the runner catches and records
+     * the error into bindState for you.
+     */
+    run(ctx: BindContext): Promise<{
+        details?: Record<string, unknown>;
+    }>;
+}
+export interface RunBindOptions {
+    archive: YithArchiveHandle;
+    tui: TuiWriter;
+    /**
+     * Phase implementations. Defaults to `defaultPhaseRunners()` when
+     * omitted. Tests pass fakes to drive the state machine without
+     * hitting the real embedding / backfill / opencode paths.
+     */
+    phases?: PhaseRunner[];
+    /**
+     * When set, runs only the listed phases (even if they're already
+     * completed). Used by `bind --force <phase>` to re-run a specific
+     * phase without touching the others. Default: respect bindState.
+     */
+    force?: BindPhase[];
+}
+/**
+ * State-machine driver. Reads bindState, runs pending phases in order,
+ * persists progress after each, halts on first failure.
+ *
+ * Returns the final BindState so callers (the CLI entry point) can
+ * summarize what happened and exit with the right code.
+ */
+export declare function runBind(opts: RunBindOptions): Promise<BindState>;
+/**
+ * Production phase runners. Tests inject fakes; the CLI entry point
+ * uses these defaults.
+ *
+ * Each runner is a thin wrapper that calls the underlying feature
+ * (provider warmup, backfill function, opencode importer, etc.) and
+ * reports progress via the context's TUI writer.
+ *
+ * Phases B, C, and D (opencode_import, sisyphus_migrate,
+ * preliminary_seed) currently register placeholders that log a
+ * "pending implementation" status and complete without work. They
+ * get real implementations in their respective phase files.
+ */
+export declare function defaultPhaseRunners(): PhaseRunner[];
+//# sourceMappingURL=bind.d.ts.map

package/dist/cli/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../../src/cli/bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAA;AAO1E,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,8CAA8C,CAAA;AACrD,OAAO,EACL,SAAS,EAMV,MAAM,UAAU,CAAA;AAMjB,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,iBAAiB,CAAA;IAC1B,GAAG,EAAE,SAAS,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAA;IACf;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAA;CACtE;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,iBAAiB,CAAA;IAC1B,GAAG,EAAE,SAAS,CAAA;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,EAAE,CAAA;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,EAAE,CAAA;CACpB;AAwBD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAqHtE;AA4DD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,IAAI,WAAW,EAAE,CA+TnD"}