codex-claude-relay 0.1.0

package/dist/cli.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { detectGitContext, getDiff } from './git.js';
+import { pickCodexSession, parseCodexSession, discoverCodexSessions, CODEX_SESSIONS_DIR, } from './providers/codex.js';
+import { pickClaudeSession, parseClaudeSession, discoverClaudeSessions, readClaudeMemory, CLAUDE_PROJECTS_DIR, } from './providers/claude.js';
+import { renderHandoff } from './summarize.js';
+import { launchAgentAsync, hasBinary } from './launch.js';
+import { DEFAULT_OPTIONS } from './types.js';
+const VERSION = '0.1.0';
+const HELP = `codex-claude-relay v${VERSION} — stateless handoff between Codex CLI and Claude Code
+
+Usage:
+  relay <target>            Launch the target agent with a handoff from the OTHER agent
+  relay preview <target>    Print the handoff that would be sent (no launch)
+  relay inspect             Show discovery results without parsing or launching
+  relay --help              Show this help
+  relay --version           Show version
+
+Targets:
+  claude   Handoff Codex -> Claude Code (reads ~/.codex/sessions, launches \`claude\`)
+  codex    Handoff Claude Code -> Codex (reads ~/.claude/projects, launches \`codex\`)
+
+Options:
+  --last              Use the most recently modified session (skip repo-relevance ranking)
+  --with-diff         Append \`git diff HEAD\` to the handoff
+  --max-chars N       Cap the handoff size (default ${DEFAULT_OPTIONS.maxChars})
+  --dry-run           Build & print the handoff, do not launch the target agent
+  --no-redact         Disable secret redaction (default: ON)
+  --debug             Verbose discovery / parsing info on stderr
+
+Examples:
+  relay claude
+  relay codex --with-diff
+  relay preview claude --max-chars 6000
+  relay inspect
+`;
+function parseArgs(argv) {
+    const positional = [];
+    const options = { ...DEFAULT_OPTIONS };
+    let cmd = 'help';
+    let target;
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h') {
+            cmd = 'help';
+            return { cmd, options, positional };
+        }
+        if (a === '--version' || a === '-v') {
+            cmd = 'version';
+            return { cmd, options, positional };
+        }
+        if (a === '--last') {
+            options.last = true;
+            i += 1;
+            continue;
+        }
+        if (a === '--with-diff') {
+            options.withDiff = true;
+            i += 1;
+            continue;
+        }
+        if (a === '--dry-run') {
+            options.dryRun = true;
+            i += 1;
+            continue;
+        }
+        if (a === '--no-redact') {
+            options.noRedact = true;
+            i += 1;
+            continue;
+        }
+        if (a === '--debug') {
+            options.debug = true;
+            i += 1;
+            continue;
+        }
+        if (a === '--max-chars') {
+            const next = argv[i + 1];
+            const n = next ? parseInt(next, 10) : NaN;
+            if (!Number.isFinite(n) || n < 500) {
+                process.stderr.write(`codex-claude-relay: --max-chars requires a positive integer >= 500\n`);
+                process.exit(2);
+            }
+            options.maxChars = n;
+            i += 2;
+            continue;
+        }
+        if (a.startsWith('--max-chars=')) {
+            const n = parseInt(a.slice('--max-chars='.length), 10);
+            if (!Number.isFinite(n) || n < 500) {
+                process.stderr.write(`codex-claude-relay: --max-chars requires a positive integer >= 500\n`);
+                process.exit(2);
+            }
+            options.maxChars = n;
+            i += 1;
+            continue;
+        }
+        if (a.startsWith('-')) {
+            process.stderr.write(`codex-claude-relay: unknown option ${a}\n`);
+            process.exit(2);
+        }
+        positional.push(a);
+        i += 1;
+    }
+    if (positional.length === 0) {
+        cmd = 'help';
+        return { cmd, options, positional };
+    }
+    const head = positional[0];
+    if (head === 'claude' || head === 'codex') {
+        cmd = head;
+        target = head;
+    }
+    else if (head === 'preview') {
+        cmd = 'preview';
+        const t = positional[1];
+        if (t === 'claude' || t === 'codex')
+            target = t;
+        else {
+            process.stderr.write(`codex-claude-relay: \`preview\` requires a target: \`relay preview claude\` or \`relay preview codex\`\n`);
+            process.exit(2);
+        }
+    }
+    else if (head === 'inspect') {
+        cmd = 'inspect';
+    }
+    else if (head === 'help') {
+        cmd = 'help';
+    }
+    else if (head === 'version') {
+        cmd = 'version';
+    }
+    else {
+        process.stderr.write(`codex-claude-relay: unknown command "${head}"\n`);
+        process.exit(2);
+    }
+    return { cmd, options, positional, target };
+}
+function debug(opts, msg) {
+    if (opts.debug)
+        process.stderr.write(`[relay] ${msg}\n`);
+}
+async function runHandoff(target, opts, mode) {
+    const git = detectGitContext(process.cwd());
+    if (!git.inRepo) {
+        process.stderr.write(`codex-claude-relay: warning — current directory is not a git repo. Falling back to cwd: ${git.root}\n`);
+    }
+    debug(opts, `git root: ${git.root} (inRepo=${git.inRepo})`);
+    const sourceAgent = target === 'claude' ? 'codex' : 'claude';
+    debug(opts, `source agent: ${sourceAgent}, target agent: ${target}`);
+    if (sourceAgent === 'codex') {
+        if (!existsSync(CODEX_SESSIONS_DIR)) {
+            process.stderr.write(`codex-claude-relay: no Codex session directory found at ${CODEX_SESSIONS_DIR}.\n` +
+                `  Run Codex CLI at least once to generate transcripts, or check ~/.codex/sessions.\n`);
+            return 1;
+        }
+        const pick = await pickCodexSession(git, opts.last);
+        if (!pick) {
+            process.stderr.write(`codex-claude-relay: no Codex rollout files found under ${CODEX_SESSIONS_DIR}.\n`);
+            return 1;
+        }
+        debug(opts, `picked codex session: ${pick.path} (score=${pick.score.toFixed(1)})`);
+        debug(opts, `reasons: ${pick.reasons.join(' | ')}`);
+        const session = await parseCodexSession(pick.path);
+        debug(opts, `parsed ${session.parsedLines} events, skipped ${session.skippedLines} malformed lines`);
+        const diff = opts.withDiff && git.inRepo ? getDiff(git.root, 6000) : null;
+        const handoff = renderHandoff({
+            sourceAgent,
+            targetAgent: target,
+            git,
+            session,
+            diff,
+            options: opts,
+        });
+        return finishHandoff(target, handoff.text, opts, mode);
+    }
+    else {
+        // sourceAgent === 'claude'
+        if (!existsSync(CLAUDE_PROJECTS_DIR)) {
+            process.stderr.write(`codex-claude-relay: no Claude Code projects directory found at ${CLAUDE_PROJECTS_DIR}.\n` +
+                `  Run Claude Code at least once to generate transcripts, or check ~/.claude/projects.\n`);
+            return 1;
+        }
+        const pick = await pickClaudeSession(git, opts.last);
+        if (!pick) {
+            process.stderr.write(`codex-claude-relay: no Claude Code session JSONLs found under ${CLAUDE_PROJECTS_DIR}.\n`);
+            return 1;
+        }
+        debug(opts, `picked claude session: ${pick.path} (score=${pick.score.toFixed(1)})`);
+        debug(opts, `reasons: ${pick.reasons.join(' | ')}`);
+        const session = await parseClaudeSession(pick.path);
+        debug(opts, `parsed ${session.parsedLines} events, skipped ${session.skippedLines} malformed lines`);
+        const mem = await readClaudeMemory(git);
+        debug(opts, `claude memory: exists=${mem.exists} bytes=${mem.summary.length}`);
+        const diff = opts.withDiff && git.inRepo ? getDiff(git.root, 6000) : null;
+        const handoff = renderHandoff({
+            sourceAgent,
+            targetAgent: target,
+            git,
+            session,
+            memorySummary: mem.exists ? mem.summary : null,
+            diff,
+            options: opts,
+        });
+        return finishHandoff(target, handoff.text, opts, mode);
+    }
+}
+async function finishHandoff(target, prompt, opts, mode) {
+    if (mode === 'preview' || opts.dryRun) {
+        if (opts.dryRun && mode === 'launch') {
+            process.stderr.write(`codex-claude-relay: --dry-run — printing handoff (would launch \`${target}\`)\n\n`);
+        }
+        process.stdout.write(prompt);
+        if (!prompt.endsWith('\n'))
+            process.stdout.write('\n');
+        return 0;
+    }
+    if (!hasBinary(target)) {
+        process.stderr.write(`codex-claude-relay: \`${target}\` is not on PATH. Install it (or use \`relay preview ${target}\` / \`--dry-run\`).\n`);
+        return 127;
+    }
+    process.stderr.write(`codex-claude-relay: launching \`${target}\` with handoff (${prompt.length} chars)\n`);
+    const res = await launchAgentAsync({ agent: target, prompt });
+    return res.code;
+}
+async function runInspect(opts) {
+    const git = detectGitContext(process.cwd());
+    const codexPaths = existsSync(CODEX_SESSIONS_DIR) ? await discoverCodexSessions(git) : [];
+    const claudePaths = existsSync(CLAUDE_PROJECTS_DIR) ? await discoverClaudeSessions(git) : [];
+    const mem = await readClaudeMemory(git);
+    const claudeOnPath = hasBinary('claude');
+    const codexOnPath = hasBinary('codex');
+    const lines = [];
+    lines.push(`codex-claude-relay v${VERSION} inspect`);
+    lines.push('');
+    lines.push(`Git context:`);
+    lines.push(`  cwd:         ${process.cwd()}`);
+    lines.push(`  inRepo:      ${git.inRepo}`);
+    lines.push(`  root:        ${git.root}`);
+    lines.push(`  branch:      ${git.branch ?? '(unknown)'}`);
+    lines.push('');
+    lines.push(`Codex sessions (~/.codex/sessions):`);
+    lines.push(`  dir exists:  ${existsSync(CODEX_SESSIONS_DIR)}`);
+    lines.push(`  count:       ${codexPaths.length}`);
+    if (codexPaths.length > 0) {
+        const best = codexPaths[0];
+        lines.push(`  best:        ${best.path}`);
+        lines.push(`               score=${best.score.toFixed(1)} mtime=${new Date(best.mtimeMs).toISOString()}`);
+        lines.push(`               cwd=${best.recordedCwd ?? '(unknown)'}`);
+        lines.push(`               reasons: ${best.reasons.join(' | ')}`);
+    }
+    lines.push('');
+    lines.push(`Claude Code sessions (~/.claude/projects):`);
+    lines.push(`  dir exists:  ${existsSync(CLAUDE_PROJECTS_DIR)}`);
+    lines.push(`  count:       ${claudePaths.length}`);
+    if (claudePaths.length > 0) {
+        const best = claudePaths[0];
+        lines.push(`  best:        ${best.path}`);
+        lines.push(`               score=${best.score.toFixed(1)} mtime=${new Date(best.mtimeMs).toISOString()}`);
+        lines.push(`               cwd=${best.recordedCwd ?? '(unknown)'}`);
+        lines.push(`               reasons: ${best.reasons.join(' | ')}`);
+    }
+    lines.push('');
+    lines.push(`Claude memory for this project:`);
+    lines.push(`  exists:      ${mem.exists}`);
+    lines.push(`  dir:         ${mem.dir}`);
+    lines.push(`  bytes:       ${mem.summary.length}`);
+    lines.push('');
+    lines.push(`Binaries on PATH:`);
+    lines.push(`  claude:      ${claudeOnPath ? 'yes' : 'NO'}`);
+    lines.push(`  codex:       ${codexOnPath ? 'yes' : 'NO'}`);
+    process.stdout.write(lines.join('\n') + '\n');
+    return 0;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const parsed = parseArgs(argv);
+    switch (parsed.cmd) {
+        case 'help':
+            process.stdout.write(HELP);
+            return 0;
+        case 'version':
+            process.stdout.write(`${VERSION}\n`);
+            return 0;
+        case 'inspect':
+            return runInspect(parsed.options);
+        case 'preview':
+            if (!parsed.target) {
+                process.stderr.write(`codex-claude-relay: missing target for preview\n`);
+                return 2;
+            }
+            return runHandoff(parsed.target, parsed.options, 'preview');
+        case 'claude':
+        case 'codex':
+            return runHandoff(parsed.cmd, parsed.options, 'launch');
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    process.stderr.write(`codex-claude-relay: unexpected error: ${err?.stack ?? err}\n`);
+    process.exit(1);
+});

package/dist/git.d.ts

@@ -0,0 +1,11 @@
+import type { GitContext } from './types.js';
+/**
+ * Detect the git context for the current working directory.
+ *
+ * If we're not inside a repo we still return a usable context (root = cwd,
+ * inRepo = false) so the rest of the pipeline degrades gracefully — callers
+ * are expected to warn when inRepo is false.
+ */
+export declare function detectGitContext(cwd?: string): GitContext;
+/** Return a short git diff (staged + unstaged) capped at maxChars. */
+export declare function getDiff(root: string, maxChars?: number): string | null;

package/dist/git.js

@@ -0,0 +1,58 @@
+import { execFileSync } from 'node:child_process';
+import { basename } from 'node:path';
+function safeGit(args, cwd) {
+    try {
+        const out = execFileSync('git', args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 3000,
+        });
+        return out.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect the git context for the current working directory.
+ *
+ * If we're not inside a repo we still return a usable context (root = cwd,
+ * inRepo = false) so the rest of the pipeline degrades gracefully — callers
+ * are expected to warn when inRepo is false.
+ */
+export function detectGitContext(cwd = process.cwd()) {
+    const root = safeGit(['rev-parse', '--show-toplevel'], cwd);
+    if (!root) {
+        return {
+            root: cwd,
+            inRepo: false,
+            repoName: basename(cwd),
+            branch: null,
+            statusShort: null,
+        };
+    }
+    const branch = safeGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], root) ??
+        safeGit(['rev-parse', '--short', 'HEAD'], root);
+    // Keep the status excerpt small — we just want a flavor for the prompt.
+    let statusShort = safeGit(['status', '--short'], root);
+    if (statusShort && statusShort.length > 2000) {
+        statusShort = statusShort.slice(0, 2000) + '\n... (truncated)';
+    }
+    return {
+        root,
+        inRepo: true,
+        repoName: basename(root),
+        branch: branch ?? null,
+        statusShort,
+    };
+}
+/** Return a short git diff (staged + unstaged) capped at maxChars. */
+export function getDiff(root, maxChars = 6000) {
+    const diff = safeGit(['diff', '--no-color', 'HEAD'], root);
+    if (!diff)
+        return null;
+    if (diff.length <= maxChars)
+        return diff;
+    return diff.slice(0, maxChars) + '\n... (diff truncated)';
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export { detectGitContext, getDiff } from './git.js';
+export { CODEX_SESSIONS_DIR, discoverCodexSessions, pickCodexSession, parseCodexSession, } from './providers/codex.js';
+export { CLAUDE_PROJECTS_DIR, discoverClaudeSessions, pickClaudeSession, parseClaudeSession, readClaudeMemory, encodeProjectDir, } from './providers/claude.js';
+export { renderHandoff } from './summarize.js';
+export { redact } from './redact.js';
+export { launchAgentAsync, hasBinary } from './launch.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+// Public programmatic API for codex-claude-relay. The CLI in src/cli.ts is the
+// primary interface, but this re-exports the building blocks for users who
+// want to embed handoff generation in their own tooling.
+export * from './types.js';
+export { detectGitContext, getDiff } from './git.js';
+export { CODEX_SESSIONS_DIR, discoverCodexSessions, pickCodexSession, parseCodexSession, } from './providers/codex.js';
+export { CLAUDE_PROJECTS_DIR, discoverClaudeSessions, pickClaudeSession, parseClaudeSession, readClaudeMemory, encodeProjectDir, } from './providers/claude.js';
+export { renderHandoff } from './summarize.js';
+export { redact } from './redact.js';
+export { launchAgentAsync, hasBinary } from './launch.js';

package/dist/launch.d.ts

@@ -0,0 +1,29 @@
+import type { AgentName } from './types.js';
+export interface LaunchResult {
+    /** Exit code of the child process. */
+    code: number;
+    /** Final argv used (for debugging / inspect). */
+    argv: string[];
+    /** Path to the temp file used, if any (cleaned up after the child exits). */
+    tempFile: string | null;
+}
+export interface LaunchOptions {
+    agent: AgentName;
+    prompt: string;
+    /** Override binary path (defaults to PATH lookup). */
+    binary?: string;
+    /** Additional CLI args to forward, placed before the prompt. */
+    extraArgs?: string[];
+}
+/** Returns true if the named binary is on PATH. */
+export declare function hasBinary(name: string): boolean;
+/**
+ * Launch the target agent with the handoff prompt as its initial input.
+ *
+ * For short prompts we pass the prompt as a positional argv item, which is the
+ * native form for both `claude` and `codex`. For long prompts we write the
+ * handoff to a 0600 temp file in a per-invocation 0700 directory and pass a
+ * short reference prompt instead — that way we never blow past the OS argv
+ * limit and never leak the handoff via process listings.
+ */
+export declare function launchAgentAsync(opts: LaunchOptions): Promise<LaunchResult>;

package/dist/launch.js

@@ -0,0 +1,66 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { writeFileSync, unlinkSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Limit beyond which we switch to a temp-file launch. */
+const ARG_INLINE_LIMIT = 8000;
+/** Returns true if the named binary is on PATH. */
+export function hasBinary(name) {
+    const res = spawnSync(process.platform === 'win32' ? 'where' : 'command', process.platform === 'win32' ? [name] : ['-v', name], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        encoding: 'utf8',
+        shell: process.platform === 'win32',
+    });
+    return res.status === 0 && (res.stdout?.trim().length ?? 0) > 0;
+}
+/**
+ * Launch the target agent with the handoff prompt as its initial input.
+ *
+ * For short prompts we pass the prompt as a positional argv item, which is the
+ * native form for both `claude` and `codex`. For long prompts we write the
+ * handoff to a 0600 temp file in a per-invocation 0700 directory and pass a
+ * short reference prompt instead — that way we never blow past the OS argv
+ * limit and never leak the handoff via process listings.
+ */
+export function launchAgentAsync(opts) {
+    const binary = opts.binary ?? opts.agent;
+    let tempFile = null;
+    let argv;
+    if (opts.prompt.length > ARG_INLINE_LIMIT) {
+        const dir = mkdtempSync(join(tmpdir(), 'codex-claude-relay-'));
+        tempFile = join(dir, 'handoff.md');
+        writeFileSync(tempFile, opts.prompt, { encoding: 'utf8', mode: 0o600 });
+        const refPrompt = `Read the handoff context file at "${tempFile}" and continue the prior session ` +
+            `(it was produced by codex-claude-relay). After reading, briefly confirm what you ` +
+            `understand the next action to be, then proceed cautiously.`;
+        argv = [...(opts.extraArgs ?? []), refPrompt];
+    }
+    else {
+        argv = [...(opts.extraArgs ?? []), opts.prompt];
+    }
+    return new Promise((resolve) => {
+        const child = spawn(binary, argv, {
+            stdio: 'inherit',
+            shell: false,
+        });
+        const cleanup = () => {
+            if (tempFile) {
+                try {
+                    unlinkSync(tempFile);
+                }
+                catch {
+                    // ignore — file may already be gone
+                }
+            }
+        };
+        child.on('exit', (code) => {
+            cleanup();
+            resolve({ code: code ?? 0, argv, tempFile });
+        });
+        child.on('error', (err) => {
+            cleanup();
+            process.stderr.write(`codex-claude-relay: failed to launch \`${binary}\`: ${err.message}\n`);
+            resolve({ code: 127, argv, tempFile });
+        });
+    });
+}

package/dist/parse/jsonl.d.ts

@@ -0,0 +1,21 @@
+export interface JsonlParseResult<T> {
+    records: T[];
+    skipped: number;
+}
+/**
+ * Stream-parse a JSONL file. Each line is fed to `accept(obj, lineNo)`; if it
+ * returns a non-null value the record is kept. Malformed lines are silently
+ * counted in `skipped`.
+ *
+ * We use streaming because Claude/Codex transcripts can be tens of megabytes,
+ * and we never need the whole raw array in memory — providers only keep the
+ * normalized events.
+ */
+export declare function parseJsonl<T>(path: string, accept: (obj: unknown, lineNo: number) => T | null): Promise<JsonlParseResult<T>>;
+/**
+ * Read just the head of a JSONL file to peek at session metadata cheaply.
+ * Returns the first N parsed objects (default 5).
+ */
+export declare function peekJsonl(path: string, n?: number): Promise<unknown[]>;
+/** Compactly truncate a string for inclusion in summaries. */
+export declare function clip(s: string, n: number): string;

package/dist/parse/jsonl.js

@@ -0,0 +1,75 @@
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+/**
+ * Stream-parse a JSONL file. Each line is fed to `accept(obj, lineNo)`; if it
+ * returns a non-null value the record is kept. Malformed lines are silently
+ * counted in `skipped`.
+ *
+ * We use streaming because Claude/Codex transcripts can be tens of megabytes,
+ * and we never need the whole raw array in memory — providers only keep the
+ * normalized events.
+ */
+export async function parseJsonl(path, accept) {
+    const records = [];
+    let skipped = 0;
+    let lineNo = 0;
+    const stream = createReadStream(path, { encoding: 'utf8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const raw of rl) {
+        lineNo += 1;
+        const line = raw.trim();
+        if (!line)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            skipped += 1;
+            continue;
+        }
+        try {
+            const kept = accept(obj, lineNo);
+            if (kept !== null && kept !== undefined) {
+                records.push(kept);
+            }
+        }
+        catch {
+            // accept() threw on a malformed-but-valid-JSON record; skip it.
+            skipped += 1;
+        }
+    }
+    return { records, skipped };
+}
+/**
+ * Read just the head of a JSONL file to peek at session metadata cheaply.
+ * Returns the first N parsed objects (default 5).
+ */
+export async function peekJsonl(path, n = 5) {
+    const out = [];
+    const stream = createReadStream(path, { encoding: 'utf8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const raw of rl) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // ignore malformed
+        }
+        if (out.length >= n) {
+            rl.close();
+            stream.destroy();
+            break;
+        }
+    }
+    return out;
+}
+/** Compactly truncate a string for inclusion in summaries. */
+export function clip(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, n) + `... (+${s.length - n} chars)`;
+}

package/dist/providers/claude.d.ts

@@ -0,0 +1,36 @@
+import type { GitContext, ParsedSession, SessionCandidate } from '../types.js';
+export declare const CLAUDE_PROJECTS_DIR: string;
+/**
+ * Claude Code encodes the project directory by replacing path separators with
+ * dashes. e.g. /Users/alice/work/foo -> -Users-alice-work-foo
+ *
+ * We can't reverse this perfectly (a `-` in a real directory name is ambiguous)
+ * but we can compute the most likely encoded name and use it as a fast-path.
+ */
+export declare function encodeProjectDir(absPath: string): string;
+/**
+ * Discover Claude session JSONL files and rank them.
+ *
+ * Strategy:
+ *   1. Fast path: try `~/.claude/projects/<encoded(root)>/*.jsonl` first; those
+ *      get a big score boost.
+ *   2. Fallback: scan the full `projects/` tree (one level deep is typical),
+ *      detect cwd from each transcript, and rank.
+ */
+export declare function discoverClaudeSessions(git: GitContext): Promise<SessionCandidate[]>;
+export declare function pickClaudeSession(git: GitContext, forceLast: boolean): Promise<SessionCandidate | null>;
+export interface ClaudeMemory {
+    exists: boolean;
+    dir: string;
+    index: string | null;
+    /** A short summary string suitable for inclusion in the handoff. */
+    summary: string;
+}
+/**
+ * Read the Claude Code auto-memory directory for the current project.
+ *
+ * Layout: `~/.claude/projects/<encoded>/memory/MEMORY.md` plus arbitrarily-named
+ * `.md` files referenced by it.
+ */
+export declare function readClaudeMemory(git: GitContext): Promise<ClaudeMemory>;
+export declare function parseClaudeSession(path: string): Promise<ParsedSession>;