send-context 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shafiq Imtiaz
+
+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,153 @@
+# send-context
+
+> Relay an AI coding-agent session from one developer to another through an encrypted, ephemeral link.
+
+`send-context` is an agent-agnostic CLI for passing live context between AI coding agents — across machines, across people, across tools. A developer in one timezone exports their session; a teammate in another runs one command to pick up exactly where they left off, with the context injected straight into *their* agent.
+
+The session is distilled into a structured **Context Handoff Skill** document, encrypted on your machine, and stored behind a short-lived link. The transport layer only ever sees ciphertext.
+
+```
+  pi / Claude Code / OpenCode                          pi / Claude Code / OpenCode
+            │                                                      ▲
+            │ extract + format                       inject prompt │
+            ▼                                                      │
+   ┌─────────────────┐   encrypt    send-context://…    decrypt   ┌─────────────────┐
+   │  send-context export │ ───────────►  edge KV (24h) ────────► │ send-context receive │
+   └─────────────────┘            (ciphertext only)          └─────────────────┘
+```
+
+## Features
+
+- **Agent-agnostic** — works with pi, [Claude Code](https://claude.com/claude-code), and [OpenCode](https://opencode.ai), via a small adapter per agent.
+- **The Context Handoff Skill Standard** — sessions become a dense, 6-section Markdown brief (objective, state, completed, failed approaches, next steps, raw appendix) instead of noisy chat logs.
+- **Zero-knowledge transport** — AES-256-GCM encryption happens client-side; the server stores only encrypted blobs that expire after 24 hours.
+- **Wrapper injection** — `send-context receive <link> -- <agent> "prompt"` launches the receiver's own agent with the context pre-loaded.
+- **No native dependencies** — pure TypeScript on Node's built-in `crypto`; installs cleanly on any OS.
+- **Serverless backend** — a ~90-line Deno Deploy worker backed by Deno KV. No credit card, no infrastructure to babysit.
+
+## How it works
+
+1. **Export** detects the active agent, extracts its session, and lets you curate what to send. You add a short written brief and pick which raw messages to attach.
+2. The brief is rendered into the Context Handoff Skill template, encrypted with a password you choose, and uploaded. You get a `send-context://` link.
+3. **Receive** downloads the blob, decrypts it locally, wraps it in an injection prompt, and spawns the receiving agent with that prompt as its opening message.
+
+> [!NOTE]
+> The password travels in the link fragment (`#…`), which is only ever processed client-side. Share the link over a channel you trust, or omit the fragment and share the password separately — `receive` will prompt for it.
+
+## Getting started
+
+### Prerequisites
+
+- Node.js 20+
+- One of: `pi`, `claude`, or `opencode` with at least one session in the project directory
+- [Deno](https://deno.com) — only if you want to deploy or run the transport worker yourself
+
+### Install
+
+```bash
+npm install
+npm run build      # compiles src/ to dist/
+node dist/index.js --help
+```
+
+To install the `send-context` command globally:
+
+```bash
+npm install -g .
+```
+
+## Deploy the transport
+
+The transport runs on **Deno Deploy + Deno KV** (`worker/main.ts`). It stores only encrypted payloads, each with a native 24-hour TTL.
+
+**From GitHub (no local Deno needed):** push the repo, then create a project at [console.deno.com](https://console.deno.com) linked to it.
+
+> [!IMPORTANT]
+> Set **App Directory** to `worker` and **Entrypoint** to `main.ts`. If the app directory is left at the repository root, the build auto-detects the Node CLI in `src/` and fails. Leave install/build commands blank.
+
+**From the CLI:**
+
+```bash
+deno install -gArf jsr:@deno/deployctl   # one-time
+cd worker
+deno task dev        # local test at http://localhost:8000
+deno task deploy     # deploys --prod, prints your *.deno.net host
+```
+
+> [!WARNING]
+> Deno KV caps each value at 64 KiB, so payloads are limited to ~60 KB. A curated context handoff is far smaller; if you hit the limit, attach fewer appendix messages.
+
+## Usage
+
+### Send a context handoff
+
+```bash
+SEND_CONTEXT_WORKER=your-project.deno.net node dist/index.js export
+# or pass the host and agent explicitly:
+node dist/index.js export --worker your-project.deno.net --agent pi
+```
+
+You'll be guided through picking the agent, writing the brief, curating the appendix, and setting a password. The command prints a link:
+
+```
+send-context://your-project.deno.net/<id>#<password>
+```
+
+### Receive a context handoff
+
+```bash
+# Launch an agent with the context injected:
+node dist/index.js receive 'send-context://…/<id>#<password>' -- pi "continue"
+node dist/index.js receive 'send-context://…/<id>#<password>' -- claude "continue"
+node dist/index.js receive 'send-context://…/<id>#<password>' -- opencode run "continue"
+
+# Or just print the decrypted context handoff document:
+node dist/index.js receive 'send-context://…/<id>#<password>'
+```
+
+## Supported agents
+
+| Agent | Extraction | Notes |
+| --- | --- | --- |
+| **OpenCode** | `opencode session list` + `opencode export <id>` | Uses the native session-export CLI. |
+| **pi** | reads `~/.pi/agent/sessions/<project>/*.jsonl` | No stdout JSON dump exists; reads the documented session transcript. |
+| **Claude Code** | reads `~/.claude/projects/<project>/*.jsonl` | Same — reads the documented JSONL transcript. |
+
+> [!TIP]
+> Adding a new agent is a single file implementing the `AgentAdapter` interface (`getName()` + `extractSession()`). Register it in `src/adapters/index.ts`.
+
+## The Context Handoff Skill Standard
+
+Every export is formatted into a fixed Markdown structure so the receiving model gets actionable context immediately:
+
+1. **Primary Objective**
+2. **Current State & Blockers**
+3. **Completed Steps** — don't repeat these
+4. **Failed Approaches** — don't retry these
+5. **Next Steps** — start here
+6. **Raw Context Appendix** — curated messages for deep context
+
+## Project structure
+
+```
+src/
+  index.ts            CLI entry (commander)
+  core/
+    crypto.ts         AES-256-GCM + scrypt
+    link.ts           send-context:// codec
+    transport.ts      upload/download client
+    formatter.ts      Context Handoff Skill renderer
+    session-store.ts  JSONL helpers
+    paths.ts exec.ts
+  adapters/           pi, claude, opencode + registry
+  commands/           export, receive
+worker/
+  main.ts             Deno Deploy + Deno KV worker
+  deno.json
+```
+
+## Tech stack
+
+- **CLI:** TypeScript, [commander](https://github.com/tj/commander.js), [@clack/prompts](https://github.com/bombshell-dev/clack)
+- **Crypto:** Node.js built-in `crypto` (AES-256-GCM, scrypt)
+- **Transport:** Deno Deploy + Deno KV

package/dist/adapters/claude.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeAdapter = void 0;
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const paths_js_1 = require("../core/paths.js");
+const session_store_js_1 = require("../core/session-store.js");
+/**
+ * Claude Code adapter.
+ *
+ * Claude Code has no stdout JSON session dump either; sessions live as
+ * documented JSONL files at ~/.claude/projects/<slug>/<id>.jsonl. We read the
+ * latest one for the current project directory.
+ */
+class ClaudeAdapter {
+    cwd;
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+    getName() {
+        return "Claude Code";
+    }
+    static isPresent(cwd = process.cwd()) {
+        return (0, node_fs_1.existsSync)((0, node_path_1.join)(paths_js_1.CLAUDE_PROJECTS_ROOT, (0, paths_js_1.claudeSlug)(cwd)));
+    }
+    async extractSession() {
+        const dir = (0, node_path_1.join)(paths_js_1.CLAUDE_PROJECTS_ROOT, (0, paths_js_1.claudeSlug)(this.cwd));
+        const file = (0, session_store_js_1.findLatestJsonl)(dir);
+        if (!file) {
+            throw new Error(`No Claude Code session found for this project (${dir}).`);
+        }
+        const messages = [];
+        for (const line of (0, session_store_js_1.readJsonl)(file)) {
+            const entry = line;
+            if (entry.type !== "user" && entry.type !== "assistant")
+                continue;
+            if (!entry.message)
+                continue;
+            const text = renderContent(entry.message.content);
+            if (!text)
+                continue;
+            messages.push({ role: entry.type, content: text });
+        }
+        return messages;
+    }
+}
+exports.ClaudeAdapter = ClaudeAdapter;
+function renderContent(content) {
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    const out = [];
+    for (const part of content) {
+        if (part.type === "text" && part.text) {
+            out.push(part.text);
+        }
+        else if (part.type === "tool_use") {
+            out.push(`[tool: ${part.name ?? "tool"}] ${(0, session_store_js_1.summarizeValue)(part.input)}`);
+        }
+        else if (part.type === "tool_result") {
+            out.push(`[tool result] ${(0, session_store_js_1.summarizeValue)(extractToolResult(part.content))}`);
+        }
+    }
+    return out.join("\n").trim();
+}
+function extractToolResult(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((p) => (p && typeof p === "object" && "text" in p ? p.text : ""))
+            .filter(Boolean)
+            .join("\n");
+    }
+    return (0, session_store_js_1.summarizeValue)(content);
+}

package/dist/adapters/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_AGENTS = void 0;
+exports.createAdapter = createAdapter;
+exports.detectAgents = detectAgents;
+const pi_js_1 = require("./pi.js");
+const claude_js_1 = require("./claude.js");
+const opencode_js_1 = require("./opencode.js");
+/** Construct an adapter by id. */
+function createAdapter(id, cwd = process.cwd()) {
+    switch (id) {
+        case "pi":
+            return new pi_js_1.PiAdapter(cwd);
+        case "claude":
+            return new claude_js_1.ClaudeAdapter(cwd);
+        case "opencode":
+            return new opencode_js_1.OpenCodeAdapter();
+    }
+}
+exports.SUPPORTED_AGENTS = ["pi", "claude", "opencode"];
+/**
+ * Auto-detect which agents have a session in the current project. Returns ids
+ * in priority order.
+ */
+function detectAgents(cwd = process.cwd()) {
+    const found = [];
+    if (pi_js_1.PiAdapter.isPresent(cwd))
+        found.push("pi");
+    if (claude_js_1.ClaudeAdapter.isPresent(cwd))
+        found.push("claude");
+    if (opencode_js_1.OpenCodeAdapter.isPresent())
+        found.push("opencode");
+    return found;
+}

package/dist/adapters/opencode.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenCodeAdapter = void 0;
+const exec_js_1 = require("../core/exec.js");
+const session_store_js_1 = require("../core/session-store.js");
+/**
+ * OpenCode adapter.
+ *
+ * OpenCode exposes a real session export CLI, so this adapter follows the
+ * "use the native CLI" rule strictly:
+ *   1. `opencode session list`   -> newest session id for this project
+ *   2. `opencode export <id>`    -> full session as JSON
+ */
+class OpenCodeAdapter {
+    static BIN = "opencode";
+    getName() {
+        return "OpenCode";
+    }
+    static isPresent() {
+        return (0, exec_js_1.commandExists)(OpenCodeAdapter.BIN);
+    }
+    async extractSession() {
+        const sessionId = await this.latestSessionId();
+        if (!sessionId) {
+            throw new Error("No OpenCode session found for this project.");
+        }
+        const { stdout, code, stderr } = await (0, exec_js_1.run)(OpenCodeAdapter.BIN, ["export", sessionId], { timeoutMs: 120_000 });
+        if (code !== 0) {
+            throw new Error(`opencode export failed: ${stderr.trim() || `exit ${code}`}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(stdout);
+        }
+        catch {
+            throw new Error("Could not parse `opencode export` output as JSON.");
+        }
+        const messages = [];
+        for (const msg of parsed.messages ?? []) {
+            const role = msg.info?.role === "assistant" ? "assistant" : "user";
+            const text = renderParts(msg.parts ?? []);
+            if (text)
+                messages.push({ role, content: text });
+        }
+        return messages;
+    }
+    async latestSessionId() {
+        const { stdout, code, stderr } = await (0, exec_js_1.run)(OpenCodeAdapter.BIN, ["session", "list"], { timeoutMs: 60_000 });
+        if (code !== 0) {
+            throw new Error(`opencode session list failed: ${stderr.trim() || `exit ${code}`}`);
+        }
+        // Rows are sorted newest-first; the id is the first `ses_…` token per line.
+        for (const line of stdout.split("\n")) {
+            const match = /\bses_\S+/.exec(line);
+            if (match)
+                return match[0];
+        }
+        return null;
+    }
+}
+exports.OpenCodeAdapter = OpenCodeAdapter;
+function renderParts(parts) {
+    const out = [];
+    for (const part of parts) {
+        if (part.type === "text" && part.text) {
+            out.push(part.text);
+        }
+        else if (part.type === "tool") {
+            const name = part.tool ?? "tool";
+            out.push(`[tool: ${name}] ${(0, session_store_js_1.summarizeValue)(part.state?.input)}`);
+        }
+        // reasoning / step-start / step-finish are skipped.
+    }
+    return out.join("\n").trim();
+}

package/dist/adapters/pi.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PiAdapter = void 0;
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const paths_js_1 = require("../core/paths.js");
+const session_store_js_1 = require("../core/session-store.js");
+/**
+ * Pi adapter.
+ *
+ * Pi has no command that dumps a session as JSON to stdout (`--mode json`
+ * starts a *new* model turn). The session itself is a documented JSONL file
+ * at ~/.pi/agent/sessions/<slug>/<id>.jsonl, so we read the latest one for the
+ * current project directory.
+ */
+class PiAdapter {
+    cwd;
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+    getName() {
+        return "Pi";
+    }
+    static isPresent(cwd = process.cwd()) {
+        return (0, node_fs_1.existsSync)((0, node_path_1.join)(paths_js_1.PI_SESSIONS_ROOT, (0, paths_js_1.piSlug)(cwd)));
+    }
+    async extractSession() {
+        const dir = (0, node_path_1.join)(paths_js_1.PI_SESSIONS_ROOT, (0, paths_js_1.piSlug)(this.cwd));
+        const file = (0, session_store_js_1.findLatestJsonl)(dir);
+        if (!file) {
+            throw new Error(`No Pi session found for this project (${dir}).`);
+        }
+        const messages = [];
+        for (const line of (0, session_store_js_1.readJsonl)(file)) {
+            const entry = line;
+            if (entry.type !== "message" || !entry.message)
+                continue;
+            const { role, content } = entry.message;
+            const text = renderParts(content);
+            if (!text)
+                continue;
+            messages.push({ role: normalizeRole(role), content: text });
+        }
+        return messages;
+    }
+}
+exports.PiAdapter = PiAdapter;
+function normalizeRole(role) {
+    if (role === "assistant")
+        return "assistant";
+    if (role === "user")
+        return "user";
+    return "system"; // toolResult and anything else
+}
+function renderParts(content) {
+    if (!Array.isArray(content))
+        return "";
+    const out = [];
+    for (const part of content) {
+        if (part.type === "text" && part.text) {
+            out.push(part.text);
+        }
+        else if (part.type === "toolCall") {
+            const name = part.name ?? part.toolName ?? "tool";
+            out.push(`[tool: ${name}] ${(0, session_store_js_1.summarizeValue)(part.args ?? part.input)}`);
+        }
+        // thinking parts are internal — skipped.
+    }
+    return out.join("\n").trim();
+}

package/dist/adapters/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentNotFoundError = void 0;
+class AgentNotFoundError extends Error {
+    binary;
+    constructor(binary) {
+        super(`Agent '${binary}' not found. Is it installed and in your PATH?`);
+        this.binary = binary;
+        this.name = "AgentNotFoundError";
+    }
+}
+exports.AgentNotFoundError = AgentNotFoundError;

package/dist/commands/export.js

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExport = runExport;
+const p = __importStar(require("@clack/prompts"));
+const index_js_1 = require("../adapters/index.js");
+const types_js_1 = require("../adapters/types.js");
+const formatter_js_1 = require("../core/formatter.js");
+const crypto_js_1 = require("../core/crypto.js");
+const transport_js_1 = require("../core/transport.js");
+const link_js_1 = require("../core/link.js");
+async function runExport(opts) {
+    p.intro("send-context export");
+    const workerHost = opts.worker ?? process.env.SEND_CONTEXT_WORKER;
+    if (!workerHost) {
+        p.cancel("No worker host. Pass --worker <host> or set SEND_CONTEXT_WORKER (e.g. your-project.deno.net).");
+        process.exitCode = 1;
+        return;
+    }
+    const agentId = await resolveAgent(opts.agent);
+    if (!agentId)
+        return;
+    const adapter = (0, index_js_1.createAdapter)(agentId);
+    const spin = p.spinner();
+    spin.start(`Extracting session from ${adapter.getName()}`);
+    let messages;
+    try {
+        messages = await adapter.extractSession();
+    }
+    catch (err) {
+        spin.stop("Extraction failed.");
+        p.cancel(err instanceof types_js_1.AgentNotFoundError ? err.message : String(err.message));
+        process.exitCode = 1;
+        return;
+    }
+    spin.stop(`Extracted ${messages.length} messages.`);
+    if (messages.length === 0) {
+        p.cancel("Session has no messages to hand off.");
+        process.exitCode = 1;
+        return;
+    }
+    const sections = await promptSections();
+    if (sections === null)
+        return;
+    const appendix = await curateAppendix(messages);
+    if (appendix === null)
+        return;
+    const markdown = (0, formatter_js_1.formatToHandoffSkill)({
+        sourceAgent: adapter.getName(),
+        timestamp: new Date().toISOString(),
+        allMessages: messages,
+        appendix,
+        sections,
+    });
+    const password = await p.password({
+        message: "Set a password (the receiver needs it to decrypt):",
+        validate: (v) => (v.length < 4 ? "Use at least 4 characters." : undefined),
+    });
+    if (p.isCancel(password)) {
+        cancelled();
+        return;
+    }
+    const payload = (0, crypto_js_1.encrypt)(markdown, password);
+    spin.start("Uploading encrypted handoff");
+    let id;
+    try {
+        id = await (0, transport_js_1.uploadPayload)(workerHost, payload);
+    }
+    catch (err) {
+        spin.stop("Upload failed.");
+        p.cancel(String(err.message));
+        process.exitCode = 1;
+        return;
+    }
+    spin.stop("Uploaded.");
+    const link = (0, link_js_1.encodeLink)({ workerHost, id, password });
+    p.note(link, "Share this link (expires in 24h)");
+    p.outro("Done.");
+}
+async function resolveAgent(preset) {
+    if (preset) {
+        if (!index_js_1.SUPPORTED_AGENTS.includes(preset)) {
+            p.cancel(`Unknown agent '${preset}'. Supported: ${index_js_1.SUPPORTED_AGENTS.join(", ")}.`);
+            process.exitCode = 1;
+            return null;
+        }
+        return preset;
+    }
+    const detected = (0, index_js_1.detectAgents)();
+    if (detected.length === 0) {
+        p.cancel("No agent session detected here. Use --agent <pi|claude|opencode>.");
+        process.exitCode = 1;
+        return null;
+    }
+    if (detected.length === 1)
+        return detected[0];
+    const choice = await p.select({
+        message: "Which agent session to hand off?",
+        options: detected.map((id) => ({ value: id, label: id })),
+    });
+    if (p.isCancel(choice)) {
+        cancelled();
+        return null;
+    }
+    return choice;
+}
+async function promptSections() {
+    const wants = await p.confirm({
+        message: "Add a written summary (objective, blockers, next steps)? Recommended.",
+        initialValue: true,
+    });
+    if (p.isCancel(wants)) {
+        cancelled();
+        return null;
+    }
+    if (!wants)
+        return {};
+    const fields = [
+        ["objective", "Primary objective"],
+        ["currentState", "Current state & blockers"],
+        ["completedSteps", "Completed steps (one per line)"],
+        ["failedApproaches", "Failed approaches — do not retry"],
+        ["nextSteps", "Next steps for the receiver"],
+    ];
+    const sections = {};
+    for (const [key, label] of fields) {
+        const value = await p.text({ message: label, placeholder: "(optional, Enter to skip)" });
+        if (p.isCancel(value)) {
+            cancelled();
+            return null;
+        }
+        if (value.trim())
+            sections[key] = value.trim();
+    }
+    return sections;
+}
+async function curateAppendix(messages) {
+    // Default to selecting the most recent 10 messages.
+    const recentFrom = Math.max(0, messages.length - 10);
+    const options = messages.map((m, i) => ({
+        value: i,
+        label: `[${m.role}] ${preview(m.content)}`,
+    }));
+    const selected = await p.multiselect({
+        message: "Select messages for the Raw Context Appendix (space to toggle):",
+        options,
+        initialValues: options.slice(recentFrom).map((o) => o.value),
+        required: false,
+    });
+    if (p.isCancel(selected)) {
+        cancelled();
+        return null;
+    }
+    return selected.map((i) => messages[i]);
+}
+function preview(content) {
+    const line = content.replace(/\s+/g, " ").trim();
+    return line.length > 80 ? `${line.slice(0, 80)}…` : line;
+}
+function cancelled() {
+    p.cancel("Cancelled.");
+    process.exitCode = 130;
+    return null;
+}

package/dist/commands/receive.js

@@ -0,0 +1,139 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReceive = runReceive;
+const node_child_process_1 = require("node:child_process");
+const p = __importStar(require("@clack/prompts"));
+const link_js_1 = require("../core/link.js");
+const transport_js_1 = require("../core/transport.js");
+const crypto_js_1 = require("../core/crypto.js");
+const INJECTION_PREAMBLE = `SYSTEM CONTEXT INJECTION:
+You are resuming a task. You have been provided with an Context Handoff Document.
+Read it carefully. Do not repeat "Completed Steps". Avoid "Failed Approaches".
+Acknowledge the "Current State" and immediately begin working on the "Next Steps".`;
+async function runReceive(rawLink, agentArgv) {
+    p.intro("send-context receive");
+    // commander hands us the literal "--" separator as the first token; drop it.
+    if (agentArgv[0] === "--")
+        agentArgv = agentArgv.slice(1);
+    let link;
+    try {
+        link = (0, link_js_1.decodeLink)(rawLink);
+    }
+    catch (err) {
+        p.cancel(String(err.message));
+        process.exitCode = 1;
+        return;
+    }
+    const spin = p.spinner();
+    spin.start("Downloading handoff");
+    let payload;
+    try {
+        payload = await (0, transport_js_1.downloadPayload)(link.workerHost, link.id);
+    }
+    catch (err) {
+        spin.stop("Download failed.");
+        const msg = err.message;
+        p.cancel(msg === "LINK_EXPIRED" ? "Link expired or invalid." : msg);
+        process.exitCode = 1;
+        return;
+    }
+    spin.stop("Downloaded.");
+    let password = link.password;
+    if (!password) {
+        const entered = await p.password({ message: "Password:" });
+        if (p.isCancel(entered)) {
+            p.cancel("Cancelled.");
+            process.exitCode = 130;
+            return;
+        }
+        password = entered;
+    }
+    let markdown;
+    try {
+        markdown = (0, crypto_js_1.decrypt)(payload, password);
+    }
+    catch (err) {
+        const msg = err.message;
+        p.cancel(msg === "INVALID_PASSWORD" ? "Invalid password." : msg);
+        process.exitCode = 1;
+        return;
+    }
+    if (agentArgv.length === 0) {
+        // No agent to launch — just print the handoff document.
+        p.outro("No agent command given; printing handoff document below.");
+        process.stdout.write(`\n${markdown}\n`);
+        return;
+    }
+    const [bin, ...rest] = agentArgv;
+    const userRequest = extractUserRequest(rest);
+    const injection = `${INJECTION_PREAMBLE}\n\n${markdown}\n\nUSER REQUEST:\n${userRequest}`;
+    p.outro(`Launching ${bin} with injected context…`);
+    await launchAgent(bin, rest, injection);
+}
+/**
+ * The trailing free-text in the agent args is treated as the user's request so
+ * it can be merged into the injection prompt. We pass the whole thing as the
+ * final positional argument to the agent CLI (the wrapper pattern), so the
+ * receiver interacts with their agent normally.
+ */
+function extractUserRequest(rest) {
+    const positional = rest.filter((a) => !a.startsWith("-"));
+    return positional.join(" ") || "Continue the work described above.";
+}
+function launchAgent(bin, rest, injection) {
+    // Replace the trailing positional prompt (if any) with the full injection;
+    // keep any flags the user passed before it.
+    const flags = rest.filter((a) => a.startsWith("-"));
+    const args = [...flags, injection];
+    return new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)(bin, args, { stdio: "inherit" });
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                process.stderr.write(`\nAgent '${bin}' not found. Is it installed and in your PATH?\n`);
+                process.exitCode = 127;
+            }
+            else {
+                process.stderr.write(`\nFailed to launch '${bin}': ${err.message}\n`);
+                process.exitCode = 1;
+            }
+            resolve();
+        });
+        child.on("close", (code) => {
+            process.exitCode = code ?? 0;
+            resolve();
+        });
+    });
+}

package/dist/core/crypto.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Zero-knowledge encryption helpers built on Node's native crypto.
+ *
+ * Scheme: AES-256-GCM. The key is derived from the password with scrypt
+ * over a per-payload random salt. The 16-byte GCM auth tag is appended to
+ * the ciphertext, so a wrong password fails authentication on decrypt.
+ */
+const ALGORITHM = "aes-256-gcm";
+const KEY_LEN = 32; // 256-bit
+const IV_LEN = 12; // GCM standard nonce length
+const SALT_LEN = 16;
+const TAG_LEN = 16;
+function deriveKey(password, salt) {
+    return (0, node_crypto_1.scryptSync)(password, salt, KEY_LEN);
+}
+function encrypt(plaintext, password) {
+    const salt = (0, node_crypto_1.randomBytes)(SALT_LEN);
+    const iv = (0, node_crypto_1.randomBytes)(IV_LEN);
+    const key = deriveKey(password, salt);
+    const cipher = (0, node_crypto_1.createCipheriv)(ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([
+        cipher.update(plaintext, "utf8"),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    return {
+        salt: salt.toString("base64"),
+        iv: iv.toString("base64"),
+        ciphertext: Buffer.concat([encrypted, tag]).toString("base64"),
+    };
+}
+function decrypt(payload, password) {
+    const salt = Buffer.from(payload.salt, "base64");
+    const iv = Buffer.from(payload.iv, "base64");
+    const data = Buffer.from(payload.ciphertext, "base64");
+    if (data.length < TAG_LEN) {
+        throw new Error("Ciphertext too short — payload is corrupt.");
+    }
+    const tag = data.subarray(data.length - TAG_LEN);
+    const encrypted = data.subarray(0, data.length - TAG_LEN);
+    const key = deriveKey(password, salt);
+    const decipher = (0, node_crypto_1.createDecipheriv)(ALGORITHM, key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([
+            decipher.update(encrypted),
+            decipher.final(),
+        ]).toString("utf8");
+    }
+    catch {
+        // GCM auth tag mismatch — wrong password or tampered payload.
+        throw new Error("INVALID_PASSWORD");
+    }
+}

package/dist/core/exec.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandExists = commandExists;
+exports.run = run;
+const node_child_process_1 = require("node:child_process");
+const types_js_1 = require("../adapters/types.js");
+/** Cheap, synchronous check that a binary is resolvable on PATH. */
+function commandExists(binary) {
+    const res = (0, node_child_process_1.spawnSync)(binary, ["--version"], { stdio: "ignore" });
+    return !res.error;
+}
+/**
+ * Run a binary and capture stdout/stderr. Rejects with AgentNotFoundError if
+ * the binary is missing (ENOENT). Never uses a shell, so arguments are passed
+ * safely without interpolation.
+ */
+function run(binary, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(binary, args, { stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.kill("SIGKILL");
+                reject(new Error(`'${binary}' timed out after ${opts.timeoutMs}ms.`));
+            }, opts.timeoutMs)
+            : null;
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (err.code === "ENOENT") {
+                reject(new types_js_1.AgentNotFoundError(binary));
+            }
+            else {
+                reject(err);
+            }
+        });
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ stdout, stderr, code });
+        });
+        if (opts.input !== undefined) {
+            child.stdin.write(opts.input);
+        }
+        child.stdin.end();
+    });
+}

package/dist/core/formatter.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToHandoffSkill = formatToHandoffSkill;
+const NOT_SPECIFIED = "_Not specified by sender._";
+function formatToHandoffSkill(input) {
+    const { sourceAgent, timestamp, appendix, allMessages, sections = {} } = input;
+    const firstUser = allMessages.find((m) => m.role === "user")?.content ?? "";
+    const originalTask = firstLine(firstUser) || NOT_SPECIFIED;
+    const objective = sections.objective?.trim() || originalTask;
+    const currentState = sections.currentState?.trim() || NOT_SPECIFIED;
+    const completedSteps = sections.completedSteps?.trim() || NOT_SPECIFIED;
+    const failedApproaches = sections.failedApproaches?.trim() || NOT_SPECIFIED;
+    const nextSteps = sections.nextSteps?.trim() || NOT_SPECIFIED;
+    return [
+        `# Context Handoff Document`,
+        `**Source Agent:** ${sourceAgent}`,
+        `**Timestamp:** ${timestamp}`,
+        `**Original Task:** ${originalTask}`,
+        ``,
+        `## 1. Primary Objective`,
+        objective,
+        ``,
+        `## 2. Current State & Blockers`,
+        currentState,
+        ``,
+        `## 3. Completed Steps`,
+        completedSteps,
+        ``,
+        `## 4. Failed Approaches (Do Not Retry)`,
+        failedApproaches,
+        ``,
+        `## 5. Next Steps`,
+        nextSteps,
+        ``,
+        `## 6. Raw Context Appendix`,
+        renderAppendix(appendix),
+        ``,
+    ].join("\n");
+}
+function renderAppendix(messages) {
+    if (messages.length === 0)
+        return "_No raw context included._";
+    return messages
+        .map((m) => {
+        const label = m.role.toUpperCase();
+        return `### ${label}\n\n${m.content.trim()}`;
+    })
+        .join("\n\n---\n\n");
+}
+function firstLine(text) {
+    const line = text
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (!line)
+        return "";
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}

package/dist/core/link.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * send-context link codec.
+ *
+ * Format: send-context://<workerHost>/<id>#<password>
+ *
+ *   - workerHost: the worker host (no scheme), e.g.
+ *     "send-context.example.deno.net". https is always assumed.
+ *   - id:         the KV record id returned by the worker on upload.
+ *   - password:   the symmetric password in the URL fragment. The fragment
+ *     never leaves the local machine when fetching (it is client-side only),
+ *     keeping the transport zero-knowledge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeLink = encodeLink;
+exports.decodeLink = decodeLink;
+exports.workerBaseUrl = workerBaseUrl;
+const LINK_RE = /^send-context:\/\/([^/]+)\/([^#]+)(?:#(.*))?$/;
+function encodeLink(link) {
+    const { workerHost, id, password } = link;
+    if (!workerHost || !id || !password) {
+        throw new Error("encodeLink: workerHost, id and password are all required.");
+    }
+    return `send-context://${stripScheme(workerHost)}/${encodeURIComponent(id)}#${encodeURIComponent(password)}`;
+}
+function decodeLink(raw) {
+    const match = LINK_RE.exec(raw.trim());
+    if (!match) {
+        throw new Error("Invalid send-context link. Expected: send-context://<host>/<id>#<password>");
+    }
+    const [, workerHost, id, password] = match;
+    return {
+        workerHost: stripScheme(workerHost),
+        id: decodeURIComponent(id),
+        password: password ? decodeURIComponent(password) : "",
+    };
+}
+/** Build the https base URL for the worker from a stored host. */
+function workerBaseUrl(workerHost) {
+    return `https://${stripScheme(workerHost)}`;
+}
+function stripScheme(host) {
+    return host.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}

package/dist/core/paths.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLAUDE_PROJECTS_ROOT = exports.PI_SESSIONS_ROOT = void 0;
+exports.piSlug = piSlug;
+exports.claudeSlug = claudeSlug;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Centralized platform paths for agent session stores. Keeping these in one
+ * place means a new agent layout only changes here.
+ */
+exports.PI_SESSIONS_ROOT = (0, node_path_1.join)((0, node_os_1.homedir)(), ".pi", "agent", "sessions");
+exports.CLAUDE_PROJECTS_ROOT = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "projects");
+/**
+ * pi encodes the project directory as a session-store folder name:
+ *   /home/x/Documents/proj  ->  --home-x-Documents-proj--
+ * (slashes become dashes, the result is wrapped in leading/trailing dashes).
+ */
+function piSlug(cwd) {
+    return `-${cwd.replace(/\//g, "-")}--`;
+}
+/**
+ * Claude Code encodes the project directory as a project folder name by
+ * replacing every non-alphanumeric character with a dash:
+ *   /home/x/Documents/proj  ->  -home-x-Documents-proj
+ */
+function claudeSlug(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}

package/dist/core/session-store.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findLatestJsonl = findLatestJsonl;
+exports.readJsonl = readJsonl;
+exports.summarizeValue = summarizeValue;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Return the newest *.jsonl file in a directory, or null if none/absent. */
+function findLatestJsonl(dir) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return null;
+    let newest = null;
+    for (const name of (0, node_fs_1.readdirSync)(dir)) {
+        if (!name.endsWith(".jsonl"))
+            continue;
+        const path = (0, node_path_1.join)(dir, name);
+        const mtime = (0, node_fs_1.statSync)(path).mtimeMs;
+        if (!newest || mtime > newest.mtime)
+            newest = { path, mtime };
+    }
+    return newest?.path ?? null;
+}
+/** Parse a JSON-lines file into objects, skipping blank/malformed lines. */
+function readJsonl(path) {
+    const out = [];
+    for (const line of (0, node_fs_1.readFileSync)(path, "utf8").split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            /* skip partial/corrupt line */
+        }
+    }
+    return out;
+}
+/** Truncate long tool payloads so the appendix stays readable. */
+function summarizeValue(value, max = 600) {
+    if (value === undefined || value === null)
+        return "";
+    const str = typeof value === "string" ? value : JSON.stringify(value);
+    return str.length > max ? `${str.slice(0, max)}… [truncated]` : str;
+}

package/dist/core/transport.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadPayload = uploadPayload;
+exports.downloadPayload = downloadPayload;
+const link_js_1 = require("./link.js");
+/** Upload an encrypted payload to the worker. Returns the stored record id. */
+async function uploadPayload(workerHost, payload) {
+    const res = await fetch(`${(0, link_js_1.workerBaseUrl)(workerHost)}/upload`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+        const serverMsg = await readError(res);
+        throw new Error(serverMsg ?? `Upload failed (HTTP ${res.status}).`);
+    }
+    const data = (await res.json());
+    if (!data.id)
+        throw new Error("Worker did not return an id.");
+    return data.id;
+}
+/** Download an encrypted payload by id. Throws LINK_EXPIRED on 404. */
+async function downloadPayload(workerHost, id) {
+    const res = await fetch(`${(0, link_js_1.workerBaseUrl)(workerHost)}/download/${encodeURIComponent(id)}`);
+    if (res.status === 404) {
+        throw new Error("LINK_EXPIRED");
+    }
+    if (!res.ok) {
+        throw new Error(`Download failed (HTTP ${res.status}).`);
+    }
+    return (await res.json());
+}
+/** Best-effort extraction of a JSON `{error}` message from a failed response. */
+async function readError(res) {
+    try {
+        const data = (await res.json());
+        return data.error ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const export_js_1 = require("./commands/export.js");
+const receive_js_1 = require("./commands/receive.js");
+const program = new commander_1.Command();
+program
+    .name("send-context")
+    .description("Relay AI coding-agent session context between developers via an encrypted, ephemeral link.")
+    .version("0.1.0")
+    .enablePositionalOptions();
+program
+    .command("export")
+    .description("Extract the current agent session, format it, encrypt it, and produce a share link.")
+    .option("-a, --agent <agent>", "force agent: pi | claude | opencode")
+    .option("-w, --worker <host>", "Cloudflare Worker host (or set SEND_CONTEXT_WORKER)")
+    .action((opts) => (0, export_js_1.runExport)({ agent: opts.agent, worker: opts.worker }));
+program
+    .command("receive")
+    .description("Download and decrypt a context handoff, then launch an agent with the context injected.")
+    .argument("<link>", "send-context:// link")
+    .argument("[agent...]", "agent command to launch after --, e.g. -- pi \"continue\"")
+    .allowUnknownOption()
+    .passThroughOptions()
+    .action((link, agent) => (0, receive_js_1.runReceive)(link, agent ?? []));
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(`\n${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "send-context",
+  "version": "0.1.0",
+  "description": "Agent-agnostic CLI to relay AI coding-agent session context between developers via an encrypted, ephemeral edge link.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "send-context": "dist/index.js"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "handoff",
+    "context",
+    "claude-code",
+    "opencode",
+    "pi",
+    "encryption"
+  ],
+  "homepage": "https://github.com/shafiqimtiaz/context-handoff#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shafiqimtiaz/context-handoff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shafiqimtiaz/context-handoff/issues"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}