@leantli/agent-handoff 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-handoff contributors
+
+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,209 @@
+# agent-handoff
+
+`agent-handoff` gives Codex and Claude Code a shared memory handoff layer across
+new sessions, fresh clones, git worktrees, and devices.
+
+A long agent session often accumulates useful context: project background,
+current task state, decisions, preferences, and repeated corrections. Without a
+handoff layer, a new session or another device starts cold.
+
+`agent-handoff` stores that context in a user-level vault, then lets any clone or
+worktree of the same repository recover it by project identity.
+
+```text
+~/.agent-handoff/vault/        # private user memory
+repo/.agent-handoff.yml        # lightweight project identity
+repo/AGENTS.md                 # Codex bootstrap instruction
+repo/CLAUDE.md                 # Claude Code bootstrap instruction
+```
+
+## Install
+
+From npm:
+
+```bash
+npm install -g @leantli/agent-handoff
+```
+
+From a checkout:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+## Three-Minute Setup
+
+Create your local vault once:
+
+```bash
+agent-handoff setup
+agent-handoff install-skill
+```
+
+Optional: sync the vault through a private git repo so another device can share
+the same handoff memory:
+
+```bash
+agent-handoff setup --sync git@github.com:you/agent-handoff-vault.git
+```
+
+Bootstrap each coding project once:
+
+```bash
+agent-handoff init
+```
+
+This writes:
+
+```text
+.agent-handoff.yml
+AGENTS.md
+CLAUDE.md
+```
+
+It does not write private memory into the project repository.
+
+## Daily Workflow
+
+At the start of a new Codex or Claude Code session:
+
+```bash
+agent-handoff sync     # only if vault sync is configured
+agent-handoff start
+```
+
+Paste or let the agent read the start packet before it works.
+
+When a useful session is about to end, or before switching devices:
+
+```bash
+agent-handoff checkpoint --note "Implemented vault storage; next step is README polish."
+agent-handoff sync     # only if vault sync is configured
+```
+
+When the user corrects a stable preference or recurring rule:
+
+```bash
+agent-handoff learn --kind preference --note "Prefer TDD for behavior changes."
+```
+
+For project-specific decisions or branch-specific context:
+
+```bash
+agent-handoff learn --scope project --kind decision --note "Use vault-first storage."
+agent-handoff learn --scope branch --kind context --note "Main is preparing v0.3."
+```
+
+When configured, `sync` commits pending vault changes and pushes them to the
+private vault repository.
+
+## Why This Solves Cross-Clone Context
+
+`agent-handoff` identifies a project from `.agent-handoff.yml` or the git
+`origin` remote. These all map to the same vault project:
+
+```text
+~/code/repo
+~/tmp/repo
+~/worktrees/repo-feature
+another device's ~/projects/repo
+```
+
+For example, both remotes below normalize to the same project id:
+
+```text
+https://github.com/leantli/agent-handoff.git
+git@github.com:leantli/agent-handoff.git
+
+github.com__leantli__agent-handoff
+```
+
+That means A session can checkpoint context into the vault, and B session can
+recover it from any clone or worktree that resolves to the same project id.
+
+## What Gets Stored
+
+The vault is private user state:
+
+```text
+~/.agent-handoff/
+  config.json
+  vault/
+    global/
+      preferences.md
+      lessons.md
+    projects/
+      github.com__owner__repo/
+        project.md
+        decisions.md
+        preferences.md
+        branches/
+          main.md
+          feature-demo.md
+        checkpoints/
+          20260508T103000Z-laptop-codex-main.md
+```
+
+The project repository gets only bootstrap files:
+
+```text
+.agent-handoff.yml
+AGENTS.md
+CLAUDE.md
+```
+
+## Commands
+
+```bash
+agent-handoff setup       # create/configure the user vault
+agent-handoff install-skill # install the agent workflow skill
+agent-handoff init        # bootstrap the current repo
+agent-handoff start       # print the context packet for a new session
+agent-handoff checkpoint  # write a session checkpoint
+agent-handoff learn       # write durable global/project/branch memory
+agent-handoff sync        # git pull/rebase + push the vault
+agent-handoff status      # quick readiness check
+agent-handoff doctor      # detailed health check
+```
+
+## Agent Skill
+
+This repo includes a Codex-compatible skill:
+
+```text
+.agents/skills/agent-handoff/SKILL.md
+```
+
+The skill tells an agent when to run `start`, `checkpoint`, `learn`, and `sync`.
+Install it into your user skills directory to make the workflow available across
+all repositories:
+
+```bash
+agent-handoff install-skill
+```
+
+The repo also keeps a copy at `.agents/skills/agent-handoff/SKILL.md` for
+project-local use.
+
+## Status
+
+This is an early prototype. It does not read proprietary chat transcripts or
+client-internal state. Agents must still call `start`, `checkpoint`, and `learn`
+at the right moments, guided by `AGENTS.md` and `CLAUDE.md`.
+
+## Development
+
+Run tests:
+
+```bash
+npm test
+```
+
+Run type checking and build:
+
+```bash
+npm run typecheck
+npm run build
+```

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = main();

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+export interface MainOptions {
+    cwd?: string;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    stdin?: {
+        isTTY?: boolean;
+    };
+}
+export declare function main(argv?: string[], opts?: MainOptions): number;

package/dist/cli.js

@@ -0,0 +1,177 @@
+import { readFileSync } from "node:fs";
+import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
+import { HandoffError, buildStartPacket, doctor, getStatus, initRepo, installSkill, learn, setupHome, syncVault, writeCheckpoint, } from "./core.js";
+export function main(argv = process.argv.slice(2), opts = {}) {
+    const stdout = opts.stdout ?? process.stdout;
+    const stderr = opts.stderr ?? process.stderr;
+    const program = buildProgram(stdout, stderr, opts.stdin, opts.cwd);
+    try {
+        program.parse(argv, { from: "user" });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            return error.exitCode;
+        }
+        if (error instanceof HandoffError) {
+            stderr.write(`${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
+function buildProgram(stdout, stderr, stdin, cwd) {
+    const program = new Command();
+    program
+        .name("agent-handoff")
+        .description("Shared vault handoff memory for Codex and Claude Code.")
+        .version("agent-handoff 0.4.0")
+        .exitOverride()
+        .configureOutput({
+        writeOut: (str) => stdout.write(str),
+        writeErr: (str) => stderr.write(str),
+    })
+        .option("--home <path>", "Agent handoff home directory. Defaults to ~/.agent-handoff.");
+    program
+        .command("setup")
+        .description("Create or configure the user vault.")
+        .option("--vault <path>", "Vault directory. Defaults to HOME/vault.")
+        .option("--sync <url>", "Optional git remote URL for vault sync.")
+        .action((options) => {
+        const result = setupHome({ home: globalHome(program), vault: options.vault, syncUrl: options.sync });
+        stdout.write(`Agent handoff home: ${result.home}\n`);
+        stdout.write(`Vault: ${result.vault}\n`);
+    });
+    program
+        .command("install-skill")
+        .description("Install the agent-handoff skill into a user skills directory.")
+        .option("--skills-home <path>", "Skills home directory. Defaults to ~/.agents/skills.")
+        .action((options) => {
+        const result = installSkill({ skillsHome: options.skillsHome });
+        const verb = result.updated ? "Installed skill" : "Skill already installed";
+        stdout.write(`${verb}: ${result.path}\n`);
+    });
+    program
+        .command("init")
+        .description("Bootstrap this repo for agent handoff.")
+        .option("--project-id <id>", "Override detected project id.")
+        .option("--branch <branch>", "Override detected branch.")
+        .addOption(new Option("--client <client>", "Client bootstrap to install. Repeat to install multiple. Defaults to both.")
+        .choices(["codex", "claude"])
+        .argParser(collect))
+        .action((options) => {
+        const result = initRepo({
+            root: cwd,
+            home: globalHome(program),
+            projectId: options.projectId,
+            branch: options.branch,
+            clients: options.client,
+        });
+        stdout.write(`Initialized agent handoff for ${result.projectId}.\n`);
+        stdout.write(`Vault project: ${result.vaultProject}\n`);
+    });
+    program
+        .command("start")
+        .description("Print context for a new agent session.")
+        .option("--branch <branch>", "Override detected branch.")
+        .action((options) => {
+        stdout.write(`${buildStartPacket({ root: cwd, home: globalHome(program), branch: options.branch })}\n`);
+    });
+    program
+        .command("checkpoint")
+        .description("Write a session checkpoint.")
+        .option("--note <text>", "Note text. If omitted, stdin is used.")
+        .option("--file <path>", "Read note text from a file.")
+        .option("--device <name>", "Device name for the checkpoint.")
+        .option("--agent <name>", "Agent/client name, such as codex or claude.")
+        .option("--branch <branch>", "Override detected branch.")
+        .action((options) => {
+        const result = writeCheckpoint({
+            root: cwd,
+            home: globalHome(program),
+            note: readNote(options, stdin),
+            device: options.device,
+            agent: options.agent,
+            branch: options.branch,
+        });
+        stdout.write(`Wrote checkpoint: ${result.path}\n`);
+    });
+    program
+        .command("learn")
+        .description("Store durable handoff memory.")
+        .option("--note <text>", "Note text. If omitted, stdin is used.")
+        .option("--file <path>", "Read note text from a file.")
+        .addOption(new Option("--scope <scope>", "Where to store the learned memory.").choices(["global", "project", "branch"]).default("global"))
+        .addOption(new Option("--kind <kind>", "Kind of durable memory to write.").choices(["preference", "lesson", "decision", "context"]).default("preference"))
+        .option("--branch <branch>", "Branch to use with --scope branch.")
+        .action((options) => {
+        const result = learn(readNote(options, stdin), {
+            root: cwd,
+            home: globalHome(program),
+            scope: options.scope,
+            kind: options.kind,
+            branch: options.branch,
+        });
+        stdout.write(`Learned ${result.kind}: ${result.path}\n`);
+    });
+    program
+        .command("sync")
+        .description("Pull and push the vault git repository.")
+        .action(() => {
+        for (const output of syncVault({ home: globalHome(program) })) {
+            if (output)
+                stdout.write(`${output}\n`);
+        }
+    });
+    program
+        .command("status")
+        .description("Show whether handoff is ready here.")
+        .action(() => {
+        const status = getStatus({ root: cwd, home: globalHome(program) });
+        if (status.initialized) {
+            stdout.write(`Agent handoff is ready for ${status.projectId}.\n`);
+        }
+        else {
+            printProblems(status.problems, stdout);
+            throw new CommanderError(1, "agent-handoff.status", "status failed");
+        }
+    });
+    program
+        .command("doctor")
+        .description("Check bootstrap and vault health.")
+        .action(() => {
+        const report = doctor({ root: cwd, home: globalHome(program) });
+        if (report.ok) {
+            stdout.write(`Agent handoff is healthy for ${report.projectId}.\n`);
+        }
+        else {
+            printProblems(report.problems, stdout);
+            throw new CommanderError(1, "agent-handoff.doctor", "doctor failed");
+        }
+    });
+    return program;
+}
+function globalHome(program) {
+    return program.opts().home;
+}
+function collect(value, previous) {
+    if (value !== "codex" && value !== "claude") {
+        throw new InvalidArgumentError("client must be codex or claude");
+    }
+    return [...(previous ?? []), value];
+}
+function readNote(options, stdin) {
+    if (options.note)
+        return options.note;
+    if (options.file)
+        return readFileSync(options.file, "utf8");
+    if (stdin?.isTTY ?? process.stdin.isTTY) {
+        throw new HandoffError("provide --note or --file, or pipe note text on stdin");
+    }
+    return readFileSync(0, "utf8");
+}
+function printProblems(problems, stdout) {
+    for (const problem of problems) {
+        stdout.write(`- ${problem}\n`);
+    }
+}

package/dist/core.d.ts

@@ -0,0 +1,103 @@
+export declare const DEFAULT_HOME: string;
+export declare const CONFIG_FILE = "config.json";
+export declare const BOOTSTRAP_FILE = ".agent-handoff.yml";
+type Client = "codex" | "claude";
+type LearnScope = "global" | "project" | "branch";
+type LearnKind = "preference" | "lesson" | "decision" | "context";
+export declare class HandoffError extends Error {
+    constructor(message: string);
+}
+export interface SetupResult {
+    home: string;
+    vault: string;
+    created: number;
+    updated: number;
+}
+export interface InitResult {
+    created: number;
+    updated: number;
+    root: string;
+    projectId: string;
+    vaultProject: string;
+    clients: Client[];
+}
+export interface CheckpointResult {
+    path: string;
+    projectId: string;
+    branch: string;
+    createdAt: string;
+}
+export interface LearnResult {
+    path: string;
+    kind: string;
+    createdAt: string;
+}
+export interface InstallSkillResult {
+    path: string;
+    updated: boolean;
+}
+export interface Status {
+    initialized: boolean;
+    problems: string[];
+    root: string;
+    projectId: string | null;
+}
+export interface DoctorReport {
+    ok: boolean;
+    problems: string[];
+    root: string;
+    projectId: string | null;
+}
+export declare function setupHome(opts?: {
+    home?: string;
+    vault?: string;
+    syncUrl?: string;
+}): SetupResult;
+export declare function normalizeProjectId(value: string): string;
+export declare function installSkill(opts?: {
+    skillsHome?: string;
+}): InstallSkillResult;
+export declare function initRepo(opts?: {
+    root?: string;
+    home?: string;
+    projectId?: string;
+    branch?: string;
+    clients?: string[];
+}): InitResult;
+export declare function deriveProjectId(root?: string, projectId?: string): string;
+export declare function currentBranch(root?: string): string;
+export declare function buildStartPacket(opts?: {
+    root?: string;
+    home?: string;
+    branch?: string;
+    maxCheckpoints?: number;
+}): string;
+export declare function writeCheckpoint(opts: {
+    root?: string;
+    note: string;
+    home?: string;
+    now?: Date;
+    device?: string;
+    agent?: string;
+    branch?: string;
+}): CheckpointResult;
+export declare function learn(note: string, opts?: {
+    home?: string;
+    root?: string;
+    scope?: LearnScope;
+    kind?: LearnKind;
+    branch?: string;
+    now?: Date;
+}): LearnResult;
+export declare function syncVault(opts?: {
+    home?: string;
+}): string[];
+export declare function getStatus(opts?: {
+    root?: string;
+    home?: string;
+}): Status;
+export declare function doctor(opts?: {
+    root?: string;
+    home?: string;
+}): DoctorReport;
+export {};

package/dist/core.js

@@ -0,0 +1,678 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { hostname, homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const DEFAULT_HOME = join(homedir(), ".agent-handoff");
+export const CONFIG_FILE = "config.json";
+export const BOOTSTRAP_FILE = ".agent-handoff.yml";
+const MANAGED_BEGIN = "<!-- BEGIN AGENT-HANDOFF -->";
+const MANAGED_END = "<!-- END AGENT-HANDOFF -->";
+const SECRET_PATTERNS = [
+    /(api[_-]?key|token|secret|password)\s*[:=]/i,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /\bsk-[A-Za-z0-9_-]{8,}\b/,
+];
+export class HandoffError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HandoffError";
+    }
+}
+export function setupHome(opts = {}) {
+    const homePath = resolveHome(opts.home);
+    const vaultPath = opts.vault ? resolve(opts.vault) : join(homePath, "vault");
+    let created = 0;
+    let updated = 0;
+    if (!existsSync(homePath)) {
+        mkdirSync(homePath, { recursive: true });
+        created += 1;
+    }
+    if (opts.syncUrl && cloneVaultIfNeeded(homePath, vaultPath, opts.syncUrl)) {
+        created += 1;
+    }
+    for (const directory of [vaultPath, join(vaultPath, "global"), join(vaultPath, "projects")]) {
+        if (!existsSync(directory)) {
+            mkdirSync(directory, { recursive: true });
+            created += 1;
+        }
+    }
+    for (const [filename, contents] of Object.entries(globalSeedFiles())) {
+        const path = join(vaultPath, "global", filename);
+        if (!existsSync(path)) {
+            writeFileSync(path, contents, "utf8");
+            created += 1;
+        }
+    }
+    const configPath = join(homePath, CONFIG_FILE);
+    const desired = { version: 2, vault: vaultPath };
+    if (opts.syncUrl)
+        desired.sync_url = opts.syncUrl;
+    if (existsSync(configPath)) {
+        const existing = JSON.parse(readFileSync(configPath, "utf8"));
+        let changed = false;
+        if (existing.version !== 2) {
+            existing.version = 2;
+            changed = true;
+        }
+        if (existing.vault !== vaultPath) {
+            existing.vault = vaultPath;
+            changed = true;
+        }
+        if (opts.syncUrl && existing.sync_url !== opts.syncUrl) {
+            existing.sync_url = opts.syncUrl;
+            changed = true;
+        }
+        if (changed) {
+            writeFileSync(configPath, json(existing), "utf8");
+            updated += 1;
+        }
+    }
+    else {
+        writeFileSync(configPath, json(desired), "utf8");
+        created += 1;
+    }
+    if (opts.syncUrl) {
+        ensureGitRemote(vaultPath, opts.syncUrl);
+    }
+    return { home: homePath, vault: vaultPath, created, updated };
+}
+export function normalizeProjectId(value) {
+    const raw = value.trim();
+    let host = "";
+    let path = "";
+    if (raw.startsWith("git@") && raw.includes(":")) {
+        const [userHost, remotePath] = raw.split(":", 2);
+        host = userHost.split("@", 2)[1] ?? "";
+        path = remotePath;
+    }
+    else if (raw.includes("://")) {
+        const parsed = new URL(raw);
+        host = parsed.hostname || parsed.host;
+        path = parsed.pathname;
+    }
+    else {
+        return safeProjectId(raw);
+    }
+    path = path.replace(/^\/+|\/+$/g, "");
+    if (path.endsWith(".git")) {
+        path = path.slice(0, -4);
+    }
+    return safeProjectId([host.toLowerCase(), ...path.split("/").filter(Boolean)].join("__"));
+}
+export function installSkill(opts = {}) {
+    const skillsHome = opts.skillsHome
+        ? resolve(opts.skillsHome)
+        : resolve(join(homedir(), ".agents", "skills"));
+    const skillDir = join(skillsHome, "agent-handoff");
+    mkdirSync(skillDir, { recursive: true });
+    const path = join(skillDir, "SKILL.md");
+    const content = readResource("agent-handoff.SKILL.md");
+    const updated = !existsSync(path) || readFileSync(path, "utf8") !== content;
+    if (updated) {
+        writeFileSync(path, content, "utf8");
+    }
+    return { path, updated };
+}
+export function initRepo(opts = {}) {
+    const rootPath = resolve(opts.root ?? ".");
+    const setup = setupHome({ home: opts.home });
+    const pid = deriveProjectId(rootPath, opts.projectId);
+    const branchName = opts.branch ?? currentBranch(rootPath);
+    const selectedClients = normalizeClients(opts.clients);
+    let created = 0;
+    let updated = 0;
+    const bootstrapPath = join(rootPath, BOOTSTRAP_FILE);
+    const bootstrapContents = `version: 2\nproject_id: ${pid}\nclients: ${selectedClients.join(",")}\n`;
+    if (!existsSync(bootstrapPath)) {
+        writeFileSync(bootstrapPath, bootstrapContents, "utf8");
+        created += 1;
+    }
+    else {
+        const data = readBootstrap(bootstrapPath);
+        const existingClients = clientsFromBootstrap(data);
+        if (data.project_id !== pid ||
+            data.version !== "2" ||
+            existingClients.join(",") !== selectedClients.join(",")) {
+            writeFileSync(bootstrapPath, bootstrapContents, "utf8");
+            updated += 1;
+        }
+    }
+    for (const filename of clientInstructionFiles(selectedClients)) {
+        const changed = ensureManagedBlock(join(rootPath, filename));
+        if (changed.changed) {
+            if (changed.created)
+                created += 1;
+            else
+                updated += 1;
+        }
+    }
+    const projectPath = vaultProjectPath(setup.vault, pid);
+    created += ensureProjectFiles(projectPath, branchName);
+    return {
+        created,
+        updated,
+        root: rootPath,
+        projectId: pid,
+        vaultProject: projectPath,
+        clients: selectedClients,
+    };
+}
+export function deriveProjectId(root = ".", projectId) {
+    const rootPath = resolve(root);
+    if (projectId)
+        return coerceProjectId(projectId);
+    const bootstrapPath = join(rootPath, BOOTSTRAP_FILE);
+    if (existsSync(bootstrapPath)) {
+        const data = readBootstrap(bootstrapPath);
+        if (data.project_id)
+            return coerceProjectId(data.project_id);
+    }
+    const remote = gitOutput(rootPath, ["remote", "get-url", "origin"]);
+    if (remote)
+        return normalizeProjectId(remote);
+    return safeProjectId(rootPath.split(/[\\/]/).pop() ?? "unknown-project");
+}
+export function currentBranch(root = ".") {
+    return gitOutput(resolve(root), ["branch", "--show-current"]) ?? "default";
+}
+export function buildStartPacket(opts = {}) {
+    const rootPath = resolve(opts.root ?? ".");
+    const status = getStatus({ root: rootPath, home: opts.home });
+    if (!status.initialized) {
+        throw new HandoffError(statusError(status));
+    }
+    const setup = loadSetup(opts.home);
+    const pid = status.projectId ?? deriveProjectId(rootPath);
+    const branchName = opts.branch ?? currentBranch(rootPath);
+    const projectPath = vaultProjectPath(setup.vault, pid);
+    const branchFile = join(projectPath, "branches", `${safeName(branchName)}.md`);
+    const sections = [
+        ["Global Preferences", join(setup.vault, "global", "preferences.md")],
+        ["Global Lessons", join(setup.vault, "global", "lessons.md")],
+        ["Project Context", join(projectPath, "project.md")],
+        ["Project Preferences", join(projectPath, "preferences.md")],
+        ["Project Decisions", join(projectPath, "decisions.md")],
+        ["Branch Context", branchFile],
+    ];
+    const lines = [
+        "# Agent Handoff Start Packet",
+        "",
+        `Project: \`${pid}\``,
+        `Branch: \`${branchName}\``,
+        "",
+        "Read this packet before making changes. Use it to recover context from previous Codex and Claude Code sessions.",
+    ];
+    for (const [title, path] of sections) {
+        lines.push(...renderSection(title, path));
+    }
+    const checkpoints = latestCheckpoints(projectPath, opts.maxCheckpoints ?? 5, branchName);
+    if (checkpoints.length > 0) {
+        lines.push("", "## Recent Checkpoints");
+        for (const path of checkpoints) {
+            lines.push(...renderSection(path.split(/[\\/]/).pop() ?? path, path, 3));
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+export function writeCheckpoint(opts) {
+    const rootPath = resolve(opts.root ?? ".");
+    const status = getStatus({ root: rootPath, home: opts.home });
+    if (!status.initialized) {
+        throw new HandoffError(statusError(status));
+    }
+    const cleanedNote = cleanNote(opts.note);
+    if (!cleanedNote)
+        throw new HandoffError("checkpoint note cannot be empty");
+    rejectLikelySecret(cleanedNote);
+    const setup = loadSetup(opts.home);
+    const pid = status.projectId ?? deriveProjectId(rootPath);
+    const branchName = opts.branch ?? currentBranch(rootPath);
+    const createdAt = timestamp(opts.now);
+    const projectPath = vaultProjectPath(setup.vault, pid);
+    const checkpoints = join(projectPath, "checkpoints");
+    mkdirSync(checkpoints, { recursive: true });
+    const deviceLabel = opts.device ?? hostname() ?? "device";
+    const agentLabel = opts.agent ?? "agent";
+    const filename = `${compactTimestamp(createdAt)}-${safeName(deviceLabel)}-${safeName(agentLabel)}-${safeName(branchName)}.md`;
+    const path = join(checkpoints, filename);
+    const contents = [
+        "# Checkpoint",
+        "",
+        `created_at: ${createdAt}`,
+        `project_id: ${pid}`,
+        `branch: ${branchName}`,
+        `device: ${deviceLabel}`,
+        `agent: ${agentLabel}`,
+        "",
+        "## Notes",
+        "",
+        cleanedNote,
+        "",
+    ].join("\n");
+    writeFileSync(path, contents, "utf8");
+    return { path, projectId: pid, branch: branchName, createdAt };
+}
+export function learn(note, opts = {}) {
+    const clean = cleanNote(note);
+    if (!clean)
+        throw new HandoffError("learn note cannot be empty");
+    rejectLikelySecret(clean);
+    const scope = opts.scope ?? "global";
+    const kind = opts.kind ?? "preference";
+    if (!["global", "project", "branch"].includes(scope)) {
+        throw new HandoffError("learn scope must be 'global', 'project', or 'branch'");
+    }
+    if (!["preference", "lesson", "decision", "context"].includes(kind)) {
+        throw new HandoffError("learn kind must be 'preference', 'lesson', 'decision', or 'context'");
+    }
+    const setup = setupHome({ home: opts.home });
+    const path = learnTargetPath(setup, resolve(opts.root ?? "."), scope, kind, opts.branch);
+    const createdAt = timestamp(opts.now);
+    appendFile(path, `\n- ${createdAt}: ${clean}\n`);
+    return { path, kind: scope === "global" ? kind : `${scope} ${kind}`, createdAt };
+}
+export function syncVault(opts = {}) {
+    const setup = loadSetup(opts.home);
+    if (!existsSync(join(setup.vault, ".git"))) {
+        throw new HandoffError("vault is not a git repository; run setup --sync first");
+    }
+    const outputs = [];
+    gitChecked(setup.vault, ["add", "-A"]);
+    const staged = gitRun(setup.vault, ["diff", "--cached", "--quiet"]).status !== 0;
+    if (staged) {
+        outputs.push(gitChecked(setup.vault, [
+            "-c",
+            "user.name=agent-handoff",
+            "-c",
+            "user.email=agent-handoff@local",
+            "commit",
+            "-m",
+            "chore: sync agent handoff vault",
+        ]));
+    }
+    const branch = gitOutput(setup.vault, ["branch", "--show-current"]) ?? "main";
+    const pull = gitRun(setup.vault, ["pull", "--rebase", "--autostash", "origin", branch]);
+    if (pull.status !== 0 && !isEmptyRemotePull(pull.output)) {
+        throw new HandoffError(pull.output.trim() || "git pull failed");
+    }
+    if (pull.output.trim())
+        outputs.push(pull.output.trim());
+    const push = gitRun(setup.vault, ["push", "-u", "origin", branch]);
+    if (push.status !== 0) {
+        throw new HandoffError(push.output.trim() || "git push failed");
+    }
+    if (push.output.trim())
+        outputs.push(push.output.trim());
+    return outputs;
+}
+export function getStatus(opts = {}) {
+    const rootPath = resolve(opts.root ?? ".");
+    const problems = [];
+    let projectId = null;
+    let clients = ["codex", "claude"];
+    const bootstrapPath = join(rootPath, BOOTSTRAP_FILE);
+    if (!existsSync(bootstrapPath)) {
+        problems.push(`${BOOTSTRAP_FILE} is missing`);
+    }
+    else {
+        const data = readBootstrap(bootstrapPath);
+        projectId = data.project_id ?? null;
+        if (!projectId)
+            problems.push(`${BOOTSTRAP_FILE} is missing project_id`);
+        clients = clientsFromBootstrap(data);
+    }
+    for (const filename of clientInstructionFiles(clients)) {
+        if (!hasManagedBlock(join(rootPath, filename))) {
+            problems.push(`${filename} is missing the managed handoff block`);
+        }
+    }
+    const config = readConfig(opts.home);
+    if (!config) {
+        problems.push("vault config is missing; run agent-handoff setup");
+    }
+    else if (!existsSync(config.vault)) {
+        problems.push(`vault directory is missing: ${config.vault}`);
+    }
+    else if (projectId) {
+        const projectPath = vaultProjectPath(config.vault, projectId);
+        if (!existsSync(projectPath)) {
+            problems.push(`vault project is missing: ${projectId}`);
+        }
+    }
+    return { initialized: problems.length === 0, problems, root: rootPath, projectId };
+}
+export function doctor(opts = {}) {
+    const status = getStatus(opts);
+    return {
+        ok: status.initialized,
+        problems: status.problems,
+        root: status.root,
+        projectId: status.projectId,
+    };
+}
+function globalSeedFiles() {
+    return {
+        "preferences.md": "# Global Preferences\n\n",
+        "lessons.md": "# Global Lessons\n\n",
+    };
+}
+function projectSeedFiles() {
+    return {
+        "project.md": "# Project Context\n\n",
+        "decisions.md": "# Decisions\n\n",
+        "preferences.md": "# Project Preferences\n\n",
+    };
+}
+function ensureProjectFiles(projectPath, branch) {
+    let created = 0;
+    for (const directory of [projectPath, join(projectPath, "branches"), join(projectPath, "checkpoints")]) {
+        if (!existsSync(directory)) {
+            mkdirSync(directory, { recursive: true });
+            created += 1;
+        }
+    }
+    for (const [filename, contents] of Object.entries(projectSeedFiles())) {
+        const path = join(projectPath, filename);
+        if (!existsSync(path)) {
+            writeFileSync(path, contents, "utf8");
+            created += 1;
+        }
+    }
+    const branchPath = join(projectPath, "branches", `${safeName(branch)}.md`);
+    if (!existsSync(branchPath)) {
+        writeFileSync(branchPath, `# Branch Context: ${branch}\n\n`, "utf8");
+        created += 1;
+    }
+    return created;
+}
+function learnTargetPath(setup, root, scope, kind, branch) {
+    if (scope === "global") {
+        if (!["preference", "lesson"].includes(kind)) {
+            throw new HandoffError("global learn kind must be 'preference' or 'lesson'");
+        }
+        return join(setup.vault, "global", kind === "preference" ? "preferences.md" : "lessons.md");
+    }
+    const status = getStatus({ root, home: setup.home });
+    if (!status.initialized) {
+        throw new HandoffError(statusError(status));
+    }
+    const pid = status.projectId ?? deriveProjectId(root);
+    const projectPath = vaultProjectPath(setup.vault, pid);
+    if (scope === "project") {
+        if (kind === "preference")
+            return join(projectPath, "preferences.md");
+        if (kind === "decision")
+            return join(projectPath, "decisions.md");
+        return join(projectPath, "project.md");
+    }
+    const branchName = branch ?? currentBranch(root);
+    const branchPath = join(projectPath, "branches", `${safeName(branchName)}.md`);
+    if (!existsSync(branchPath)) {
+        writeFileSync(branchPath, `# Branch Context: ${branchName}\n\n`, "utf8");
+    }
+    return branchPath;
+}
+function normalizeClients(clients) {
+    const selected = clients && clients.length > 0 ? clients : ["codex", "claude"];
+    const deduped = [];
+    for (const client of selected) {
+        if (client !== "codex" && client !== "claude") {
+            throw new HandoffError(`unsupported client(s): ${client}`);
+        }
+        if (!deduped.includes(client))
+            deduped.push(client);
+    }
+    return deduped;
+}
+function clientsFromBootstrap(data) {
+    if (!data.clients)
+        return ["codex", "claude"];
+    return normalizeClients(data.clients.split(",").map((client) => client.trim()).filter(Boolean));
+}
+function clientInstructionFiles(clients) {
+    const files = [];
+    if (clients.includes("codex"))
+        files.push("AGENTS.md");
+    if (clients.includes("claude"))
+        files.push("CLAUDE.md");
+    return files;
+}
+function resolveHome(home) {
+    return resolve(home ? expandHome(home) : DEFAULT_HOME);
+}
+function expandHome(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+function readConfig(home) {
+    const configPath = join(resolveHome(home), CONFIG_FILE);
+    if (!existsSync(configPath))
+        return null;
+    return JSON.parse(readFileSync(configPath, "utf8"));
+}
+function loadSetup(home) {
+    const config = readConfig(home);
+    if (!config)
+        return setupHome({ home });
+    return { home: resolveHome(home), vault: resolve(config.vault), created: 0, updated: 0 };
+}
+function vaultProjectPath(vault, projectId) {
+    return join(vault, "projects", coerceProjectId(projectId));
+}
+function coerceProjectId(value) {
+    if (value.includes("://") || value.startsWith("git@"))
+        return normalizeProjectId(value);
+    return safeProjectId(value);
+}
+function safeProjectId(value) {
+    let normalized = value.trim().replace(/^\/+|\/+$/g, "");
+    if (normalized.endsWith(".git"))
+        normalized = normalized.slice(0, -4);
+    normalized = normalized.replace(/[/:]/g, "__").replace(/[^A-Za-z0-9._-]+/g, "__");
+    normalized = normalized.replace(/__+/g, "__").replace(/^_+|_+$/g, "");
+    return normalized || "unknown-project";
+}
+function safeName(value) {
+    const normalized = value.trim().replace(/[^A-Za-z0-9._-]+/g, "__").replace(/__+/g, "__").replace(/^_+|_+$/g, "");
+    return normalized || "default";
+}
+function readBootstrap(path) {
+    const data = {};
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+        if (!line.includes(":") || line.trimStart().startsWith("#"))
+            continue;
+        const index = line.indexOf(":");
+        data[line.slice(0, index).trim()] = line.slice(index + 1).trim().replace(/^["']|["']$/g, "");
+    }
+    return data;
+}
+function managedBlock() {
+    return [
+        MANAGED_BEGIN,
+        "Agent handoff is enabled for this repository.",
+        "",
+        "At the start of a new Codex or Claude Code session, run `agent-handoff sync` if vault sync is configured, then run:",
+        "",
+        "```bash",
+        "agent-handoff start",
+        "```",
+        "",
+        "Read the returned packet before making changes.",
+        "",
+        "Before pausing work, switching devices, or ending a useful session, run:",
+        "",
+        "```bash",
+        'agent-handoff checkpoint --note "<current goal, progress, open questions, next step>"',
+        "```",
+        "",
+        "Then run `agent-handoff sync` if vault sync is configured.",
+        "",
+        'When the user corrects a stable preference or recurring rule, run `agent-handoff learn --kind preference --note "..."`.',
+        MANAGED_END,
+        "",
+    ].join("\n");
+}
+function ensureManagedBlock(path) {
+    const block = managedBlock();
+    if (!existsSync(path)) {
+        writeFileSync(path, block, "utf8");
+        return { changed: true, created: true };
+    }
+    const original = readFileSync(path, "utf8");
+    let updated;
+    if (original.includes(MANAGED_BEGIN) && original.includes(MANAGED_END)) {
+        const before = original.split(MANAGED_BEGIN, 1)[0];
+        const after = original.split(MANAGED_END, 2)[1] ?? "";
+        const parts = [];
+        if (before.trimEnd())
+            parts.push(before.trimEnd());
+        parts.push(block.trimEnd());
+        if (after.trimStart())
+            parts.push(after.trimStart());
+        updated = `${parts.join("\n\n")}\n`;
+    }
+    else {
+        updated = `${original.trimEnd()}\n\n${block}`;
+    }
+    if (updated !== original) {
+        writeFileSync(path, updated, "utf8");
+        return { changed: true, created: false };
+    }
+    return { changed: false, created: false };
+}
+function hasManagedBlock(path) {
+    if (!existsSync(path))
+        return false;
+    const contents = readFileSync(path, "utf8");
+    return contents.includes(MANAGED_BEGIN) && contents.includes(MANAGED_END);
+}
+function renderSection(title, path, headingLevel = 2) {
+    const heading = "#".repeat(headingLevel);
+    if (!existsSync(path)) {
+        return ["", `${heading} ${title}`, "", "_Missing._"];
+    }
+    return ["", `${heading} ${title}`, "", readFileSync(path, "utf8").trimEnd()];
+}
+function latestCheckpoints(projectPath, limit, branch) {
+    const checkpointDir = join(projectPath, "checkpoints");
+    if (!existsSync(checkpointDir))
+        return [];
+    let paths = readdirSync(checkpointDir)
+        .filter((name) => name.endsWith(".md"))
+        .sort()
+        .map((name) => join(checkpointDir, name));
+    if (branch !== undefined) {
+        paths = paths.filter((path) => checkpointBranch(path) === branch);
+    }
+    return paths.slice(-limit);
+}
+function checkpointBranch(path) {
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+        if (line.startsWith("branch:"))
+            return line.split(":", 2)[1].trim();
+    }
+    return null;
+}
+function timestamp(now) {
+    const value = now ?? new Date();
+    const year = value.getUTCFullYear();
+    const month = pad(value.getUTCMonth() + 1);
+    const day = pad(value.getUTCDate());
+    const hour = pad(value.getUTCHours());
+    const minute = pad(value.getUTCMinutes());
+    const second = pad(value.getUTCSeconds());
+    return `${year}-${month}-${day}T${hour}:${minute}:${second}+00:00`;
+}
+function compactTimestamp(value) {
+    return value.replace("+00:00", "Z").replace(/[:.-]/g, "");
+}
+function pad(value) {
+    return value.toString().padStart(2, "0");
+}
+function cleanNote(note) {
+    return note
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .trim();
+}
+function rejectLikelySecret(note) {
+    if (SECRET_PATTERNS.some((pattern) => pattern.test(note))) {
+        throw new HandoffError("handoff notes look like they contain a secret; remove it and try again");
+    }
+}
+function statusError(status) {
+    return `agent handoff is not ready:\n${status.problems.map((problem) => `- ${problem}`).join("\n")}`;
+}
+function json(data) {
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
+function appendFile(path, contents) {
+    writeFileSync(path, contents, { encoding: "utf8", flag: "a" });
+}
+function cloneVaultIfNeeded(home, vault, syncUrl) {
+    if (existsSync(join(vault, ".git")))
+        return false;
+    if (existsSync(vault)) {
+        if (readdirSync(vault).length === 0) {
+            rmSync(vault, { recursive: true, force: true });
+        }
+        else {
+            return false;
+        }
+    }
+    const clone = gitRun(home, ["clone", syncUrl, vault]);
+    return clone.status === 0;
+}
+function ensureGitRemote(vault, syncUrl) {
+    if (!existsSync(join(vault, ".git"))) {
+        gitRun(vault, ["init"]);
+        gitRun(vault, ["branch", "-M", "main"]);
+    }
+    const remotes = gitOutput(vault, ["remote"]);
+    if (remotes?.split(/\r?\n/).includes("origin")) {
+        gitRun(vault, ["remote", "set-url", "origin", syncUrl]);
+    }
+    else {
+        gitRun(vault, ["remote", "add", "origin", syncUrl]);
+    }
+}
+function gitOutput(root, args) {
+    const result = gitRun(root, args);
+    if (result.status !== 0)
+        return null;
+    const output = result.output.trim();
+    return output || null;
+}
+function gitChecked(root, args) {
+    const result = gitRun(root, args);
+    if (result.status !== 0) {
+        throw new HandoffError(result.output.trim() || `git ${args.join(" ")} failed`);
+    }
+    return result.output.trim();
+}
+function gitRun(root, args) {
+    const result = spawnSync("git", args, {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        status: result.status ?? 1,
+        output: `${result.stdout ?? ""}${result.stderr ?? ""}`,
+    };
+}
+function isEmptyRemotePull(output) {
+    const lowered = output.toLowerCase();
+    return lowered.includes("couldn't find remote ref") || lowered.includes("could not find remote ref");
+}
+function readResource(name) {
+    const path = fileURLToPath(new URL(`../resources/${name}`, import.meta.url));
+    return readFileSync(path, "utf8");
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./core.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./core.js";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@leantli/agent-handoff",
+  "version": "0.4.0",
+  "description": "Shared vault handoff memory for Codex and Claude Code.",
+  "type": "module",
+  "license": "MIT",
+  "author": "agent-handoff contributors",
+  "bin": {
+    "agent-handoff": "dist/bin.js"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "resources",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "codex",
+    "claude-code",
+    "handoff",
+    "context"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  }
+}

package/resources/agent-handoff.SKILL.md

@@ -0,0 +1,72 @@
+---
+name: agent-handoff
+description: Use when starting, resuming, pausing, checkpointing, or transferring Codex/Claude Code work across sessions, clones, worktrees, or devices with the agent-handoff CLI.
+---
+
+# Agent Handoff
+
+Use `agent-handoff` to restore and preserve coding-agent context.
+
+## Start Of Session
+
+When beginning work in a repository:
+
+1. Run `agent-handoff status`.
+2. If status says the repo is not ready, run `agent-handoff setup` if the vault is missing, then `agent-handoff init`.
+3. If vault sync is configured, run `agent-handoff sync`.
+4. Run `agent-handoff start`.
+5. Read the returned packet before changing files.
+
+## During Work
+
+Use `learn` only for stable facts that should survive future sessions, clones,
+worktrees, and devices.
+
+For a durable user preference or recurring correction:
+
+```bash
+agent-handoff learn --kind preference --note "<stable preference>"
+```
+
+For a durable lesson about project or agent behavior:
+
+```bash
+agent-handoff learn --kind lesson --note "<stable lesson>"
+```
+
+For project-specific decisions:
+
+```bash
+agent-handoff learn --scope project --kind decision --note "<project decision>"
+```
+
+For branch-specific current context:
+
+```bash
+agent-handoff learn --scope branch --kind context --note "<branch context>"
+```
+
+## Before Pausing
+
+Before ending a useful session, switching devices, or handing work to another
+agent, write a concise checkpoint:
+
+```bash
+agent-handoff checkpoint --note "<current goal, completed work, open questions, next step>"
+```
+
+If vault sync is configured, run:
+
+```bash
+agent-handoff sync
+```
+
+If sync fails, keep the local checkpoint and report the error.
+
+## Rules
+
+- Do not store secrets, tokens, credentials, or private customer data in handoff notes.
+- Keep checkpoints factual and concise.
+- Do not use `learn` for temporary task state; use `checkpoint` instead.
+- Prefer project or branch scope for project-specific facts instead of global memory.
+- If `agent-handoff` is not installed, tell the user the CLI is missing and continue without pretending context was saved.