sandhop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talking Computers
+
+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,128 @@
+# Sandhop
+
+Sandhop teleports a live local Claude Code or Codex session to a cloud sandbox and lets you continue it in an auth-gated browser terminal. It sends the dirty working tree, the active transcript, and the agent auth needed to resume the same session remotely — no commit, no context re-injection, native `--resume`.
+
+## Why Sandhop
+
+Claude on the web and Codex cloud are good for clean repo tasks. Sandhop is for the messy local moment: uncommitted files, generated state, local slash commands, MCP config, and either Claude Code or Codex. The wedge is dirty-tree + cross-tool teleport, not another hosted agent UI.
+
+## Quickstart
+
+```bash
+npm install -g sandhop
+sandhop setup
+```
+
+`sandhop setup` is a short wizard: pick your sandbox provider, paste its API key, choose a transport, and it installs the `/sandhop` command into whichever agents you have (Claude Code and/or Codex). Credentials are stored in `~/.config/sandhop/config.json` (mode 600). You are never asked for your Claude/Codex API key — that auth is captured from your existing local session at teleport time.
+
+Then, from inside any Claude Code or Codex session in a project:
+
+```text
+/sandhop
+```
+
+It runs `sandhop push` for the current session and prints the web-terminal URL:
+
+```text
+SANDHOP_URL  https://<host>
+SANDHOP_AUTH sandhop:<password>
+```
+
+Open `SANDHOP_URL` and sign in with the `SANDHOP_AUTH` user/password to continue your session in the browser.
+
+## Sandbox providers
+
+Sandhop is provider-agnostic. `sandhop setup` configures the default; override per-run with `--provider`.
+
+| Provider           | `--provider` | Credentials (collected by `sandhop setup`)             |
+| ------------------ | ------------ | ----------------------------------------------------- |
+| **E2B** (default)  | `e2b`        | `E2B_API_KEY`                                         |
+| **Modal**          | `modal`      | `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET`                |
+| **Daytona**        | `daytona`    | `DAYTONA_API_KEY` (+ optional `DAYTONA_TARGET`)       |
+| **Vercel Sandbox** | `vercel`     | `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID` |
+
+Each provider SDK is an optional dependency, loaded lazily — installing Sandhop does not pull all four. The CLI resolves credentials **environment first, then the `sandhop setup` store**, so CI/scripts can just export the env vars and skip setup.
+
+## Usage
+
+```bash
+sandhop push                              # teleport the latest session in $(pwd)
+sandhop push --provider modal             # choose a provider for this run
+sandhop push --tunnel cloudflared         # private/portable URL (see below)
+sandhop push --agent codex --session <id> # pin the agent and a specific session
+sandhop push --no-profile                 # core only: working tree + transcript
+sandhop list                              # list running sandboxes
+sandhop kill <sandbox-id>                 # destroy a sandbox
+```
+
+(`sandhop` is the global bin; `node dist/cli/main.js <cmd>` is equivalent from source.)
+
+### Flags
+
+- `--provider e2b|modal|daytona|vercel` — sandbox provider (default: configured / `e2b`).
+- `--tunnel public|cloudflared` — URL transport (default: configured / `public`).
+- `--agent claude-code|codex` — force the agent (default: auto-detect from the cwd's sessions).
+- `--session <id>` — resume a specific session instead of the newest for the cwd.
+- `--no-profile` — skip profile/plugin/skill/MCP enrichment; the working tree + transcript still move.
+- `--cwd <path>` — operate on a directory other than the process cwd.
+
+## Transports / private access
+
+- **`--tunnel public`** (default): exposes ttyd through the provider's HTTPS preview, gated by Sandhop's per-teleport ttyd Basic Auth.
+- **`--tunnel cloudflared`**: binds ttyd to loopback and runs cloudflared inside the sandbox. Works through provider egress where native expose is token-gated (e.g. Daytona).
+  - _Quick tunnel_ (default): zero-config `*.trycloudflare.com` URL + Basic Auth.
+  - _Named tunnel_ (Access-gated, private): set `CLOUDFLARE_TUNNEL_TOKEN` + `CLOUDFLARE_TUNNEL_HOSTNAME` (or via `sandhop setup`); Sandhop returns `https://<your-hostname>` and Cloudflare Access enforces login.
+
+## What transfers
+
+- **Working tree** — full dirty/uncommitted state, restored at its original absolute path so the resumed session's recorded cwd matches.
+- **Transcript** — the exact session file; resumed natively (`claude --resume` / `codex resume`), not re-injected.
+- **Agent auth** — Claude/Codex credentials shipped as sandbox env/credential files over TLS, never inside the project tarball.
+- **Profile** (enrichment) — settings, `CLAUDE.md`/`AGENTS.md`, commands, skills, plugins; plugins/skills are rebuilt from manifests/refs in-cloud (byte-equivalent versions) rather than bulk-uploaded.
+- **MCP servers** — config + referenced env/secrets + local-path server code, with a raised startup timeout so `npx`-based servers finish installing. Servers that cannot run in a fresh sandbox (localhost/loopback DSNs, etc.) are excluded with a logged reason.
+
+## How it works
+
+1. **Fast core**: collect the working-tree root, transcript, auth, secrets, and local CLI version in parallel; create a single-tenant ephemeral sandbox; upload the bundle + transcript; install the matching agent CLI; restore the transcript; start ttyd; return the URL. Target: under ~2 minutes for ordinary projects.
+2. **Detached enrichment**: transfer portable profile + MCP local code, then rebuild reproducible plugins/skills/deps from manifests so the URL stays fast.
+
+## Security model
+
+- Single-tenant ephemeral sandbox per push; auth/secrets travel as env/credential files over TLS, not in the tarball.
+- Default access is HTTPS + per-teleport ttyd Basic Auth; `--tunnel cloudflared` adds quick-tunnel or Access-gated named-tunnel options.
+- Sandhop never logs secret values.
+- Destroy a sandbox with `sandhop kill <sandbox-id>`.
+
+## Architecture
+
+TypeScript modular monolith with a hexagonal core. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+- `src/core`: ports, pure data types, orchestration services (teleport, enrichment, snapshot, profile, secrets, MCP).
+- `src/host`: local Node filesystem/process/keychain/tar adapter.
+- `src/providers`: sandbox provider adapters — E2B, Modal, Daytona, Vercel — behind one `SandboxProvider` port + registry.
+- `src/agents`: Claude Code and Codex adapters behind one `Agent` port.
+- `src/transports`: `public` (provider URL) and `cloudflared` URL adapters.
+- `src/cli`: composition root, `sandhop setup` wizard, and CLI entrypoints.
+- `plugin/`: the `/sandhop` command (`commands/`) and prompt (`prompts/`) wrappers installed by `sandhop setup`.
+
+## Limitations
+
+- You need an existing local Claude Code or Codex session for the target cwd.
+- Large dirty trees take time to archive and upload.
+- Enrichment can finish after the terminal is usable; check `/tmp/sandhop-enrich.log` inside the sandbox.
+- MCP servers that depend on local-only resources (localhost databases, local data files, a browser) or that require interactive OAuth (e.g. Notion, Ramp) won't function in a fresh sandbox — log in inside the sandbox, or expect them absent/unauthenticated.
+- **Codex resume is org-bound**: it replays the session's encrypted reasoning to the API, so the shipped credential must belong to the org that created the rollout. The default `~/.codex/auth.json` ships as-is (fine for ordinary OpenAI logins). Sessions created under a custom provider profile (e.g. Azure) resume only with that provider's credential; ChatGPT-OAuth `auth.json` (no `OPENAI_API_KEY`) is unverified for cross-machine resume.
+- The agent CLI installs at your exact local version, so Codex may show its standard "update available" notice — informational; choose "skip" to continue.
+- Cloud rebuilds need network access to the git/npm/bun/uv sources referenced by your manifests.
+
+## Development
+
+```bash
+npm ci
+npm run build
+npx vitest run
+```
+
+## License
+
+MIT © Talking Computers

package/dist/agents/claude-code.js

@@ -0,0 +1,178 @@
+import { projectDirName } from "../core/encode.js";
+import { collectEnvRefs } from "../core/env.js";
+import { isRecord } from "../core/json.js";
+import { MCP_TIMEOUT_MS } from "../core/mcp-timeout.js";
+import { basename } from "../core/paths.js";
+import { buildClaudePreSeedScript } from "../core/sandbox-scripts.js";
+import { makeVersionParser, sortNewest } from "./shared.js";
+import { CLAUDE_JSON_HOME_PATH, CLAUDE_JSON_PATH, CLAUDE_MCP_PATH, CLAUDE_PROFILE_PATHS, CLAUDE_PROJECTS_PATH, CLAUDE_SETTINGS_LOCAL_PATH, CLAUDE_SETTINGS_PATH, joinClaudeHomePath, joinClaudeLocalPath, } from "./claude-paths.js";
+const addJsonEnvRefs = (refs, value) => {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            addJsonEnvRefs(refs, item);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "env" && isRecord(child)) {
+            for (const name of Object.keys(child))
+                refs.add(name);
+        }
+        addJsonEnvRefs(refs, child);
+    }
+};
+const readJsonEnvRefs = (text) => {
+    const refs = new Set();
+    for (const name of collectEnvRefs(text))
+        refs.add(name);
+    try {
+        addJsonEnvRefs(refs, JSON.parse(text));
+    }
+    catch {
+        return [...refs].sort();
+    }
+    return [...refs].sort();
+};
+const parseVersion = makeVersionParser("claude-code");
+const authEnv = (deps) => {
+    const envKey = deps.env.ANTHROPIC_API_KEY;
+    if (envKey !== undefined && envKey.startsWith("sk-ant-"))
+        return { envs: { ANTHROPIC_API_KEY: envKey }, files: [] };
+    const keychainKey = deps.keychain("Claude Code", null);
+    if (keychainKey !== null && keychainKey.startsWith("sk-ant-"))
+        return { envs: { ANTHROPIC_API_KEY: keychainKey }, files: [] };
+    const oauth = deps.env.CLAUDE_CODE_OAUTH_TOKEN;
+    if (oauth !== undefined)
+        return { envs: { CLAUDE_CODE_OAUTH_TOKEN: oauth }, files: [] };
+    throw new Error("No Claude Code credential. Run: claude setup-token, then export CLAUDE_CODE_OAUTH_TOKEN");
+};
+const readStringArray = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    const values = [];
+    for (const item of value) {
+        if (typeof item !== "string")
+            return undefined;
+        values.push(item);
+    }
+    return values;
+};
+const readStringRecord = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    const record = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== "string")
+            return undefined;
+        record[key] = item;
+    }
+    return record;
+};
+const readTransport = (value, hasUrl) => {
+    if (value === "sse")
+        return "sse";
+    if (value === "http" || hasUrl)
+        return "http";
+    return "stdio";
+};
+const readMcpServers = (value, servers) => {
+    if (!isRecord(value))
+        return;
+    for (const [name, server] of Object.entries(value)) {
+        if (!isRecord(server))
+            continue;
+        const command = typeof server.command === "string" ? server.command : undefined;
+        const url = typeof server.url === "string" ? server.url : undefined;
+        if (command === undefined && url === undefined)
+            continue;
+        const args = readStringArray(server.args);
+        const env = readStringRecord(server.env);
+        const cwd = typeof server.cwd === "string" ? server.cwd : undefined;
+        servers.push({
+            name,
+            transport: readTransport(server.transport, url !== undefined),
+            ...(command === undefined ? {} : { command }),
+            ...(args === undefined ? {} : { args }),
+            ...(env === undefined ? {} : { env }),
+            ...(cwd === undefined ? {} : { cwd }),
+            ...(url === undefined ? {} : { url }),
+        });
+    }
+};
+const parseMcpServers = (deps, cwd) => {
+    const servers = [];
+    const claudeJson = deps.readFile(joinClaudeLocalPath(deps.home, CLAUDE_JSON_PATH));
+    if (claudeJson !== null) {
+        const parsed = JSON.parse(claudeJson);
+        if (isRecord(parsed)) {
+            readMcpServers(parsed.mcpServers, servers);
+            const projects = parsed.projects;
+            if (isRecord(projects)) {
+                const project = projects[cwd];
+                if (isRecord(project))
+                    readMcpServers(project.mcpServers, servers);
+            }
+        }
+    }
+    const mcpJson = deps.readFile(`${cwd}/.mcp.json`);
+    if (mcpJson !== null) {
+        const parsed = JSON.parse(mcpJson);
+        if (isRecord(parsed))
+            readMcpServers(parsed.mcpServers, servers);
+    }
+    return servers;
+};
+const formatMcpConfig = (servers) => {
+    const mcpServers = {};
+    for (const server of servers) {
+        const { name, ...config } = server;
+        mcpServers[name] = config;
+    }
+    return {
+        path: CLAUDE_JSON_HOME_PATH,
+        content: `${JSON.stringify(mcpServers, null, 2)}\n`,
+        mode: "merge-claude-json",
+    };
+};
+export const CLAUDE_CODE = {
+    id: "claude-code",
+    pkg: "@anthropic-ai/claude-code",
+    bin: "claude",
+    detectVersionArgs: ["--version"],
+    parseVersion,
+    matchSession: (deps, cwd) => {
+        const root = `${joinClaudeLocalPath(deps.home, CLAUDE_PROJECTS_PATH)}/${projectDirName(cwd)}`;
+        return sortNewest(deps, deps
+            .walk(root)
+            .filter((path) => path.endsWith(".jsonl"))
+            .map((path) => {
+            const name = basename(path);
+            return {
+                sessionId: name.replace(/\.jsonl$/, ""),
+                transcriptPath: path,
+                transcriptName: name,
+            };
+        }));
+    },
+    profilePaths: () => [...CLAUDE_PROFILE_PATHS],
+    mcpConfigPaths: (home, cwd) => [
+        `${cwd}/.mcp.json`,
+        joinClaudeLocalPath(home, CLAUDE_SETTINGS_PATH),
+        joinClaudeLocalPath(home, CLAUDE_SETTINGS_LOCAL_PATH),
+        joinClaudeLocalPath(home, CLAUDE_MCP_PATH),
+        joinClaudeLocalPath(home, CLAUDE_JSON_PATH),
+    ],
+    mcpEnvRefs: readJsonEnvRefs,
+    parseMcpServers,
+    formatMcpConfig,
+    authEnv,
+    installCmd: (version) => `npm i -g @anthropic-ai/claude-code@${version}`,
+    supportsSettingsScripts: () => true,
+    supportsReinstall: () => true,
+    preSeed: (remoteProj) => [
+        `node -e ${JSON.stringify(buildClaudePreSeedScript(remoteProj))}`,
+    ],
+    remoteTranscriptPath: (remoteEnc, transcriptName) => `${joinClaudeHomePath(CLAUDE_PROJECTS_PATH)}/${remoteEnc}/${transcriptName}`,
+    resumeCmd: (sessionId, remoteProj) => `cd "${remoteProj}" && MCP_TIMEOUT=${MCP_TIMEOUT_MS} claude --resume ${sessionId}`,
+};

package/dist/agents/claude-paths.js

@@ -0,0 +1,36 @@
+export const CLAUDE_JSON_PATH = ".claude.json";
+export const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
+export const CLAUDE_SETTINGS_LOCAL_PATH = ".claude/settings.local.json";
+export const CLAUDE_INSTRUCTIONS_PATH = ".claude/CLAUDE.md";
+export const CLAUDE_COMMANDS_PATH = ".claude/commands";
+export const CLAUDE_SKILLS_PATH = ".claude/skills";
+export const CLAUDE_AGENTS_PATH = ".claude/agents";
+export const CLAUDE_OUTPUT_STYLES_PATH = ".claude/output-styles";
+export const CLAUDE_MCP_PATH = ".claude/mcp.json";
+export const CLAUDE_PLUGINS_PATH = ".claude/plugins";
+export const CLAUDE_PROJECTS_PATH = ".claude/projects";
+export const CLAUDE_KNOWN_MARKETPLACES_PATH = ".claude/plugins/known_marketplaces.json";
+export const CLAUDE_INSTALLED_PLUGINS_PATH = ".claude/plugins/installed_plugins.json";
+export const CLAUDE_JSON_HOME_PATH = "$HOME/.claude.json";
+export const CLAUDE_SETTINGS_SANDBOX_PATH = "/home/user/.claude/settings.json";
+export const CLAUDE_PROFILE_PATHS = [
+    CLAUDE_SETTINGS_PATH,
+    CLAUDE_SETTINGS_LOCAL_PATH,
+    CLAUDE_INSTRUCTIONS_PATH,
+    CLAUDE_COMMANDS_PATH,
+    CLAUDE_SKILLS_PATH,
+    CLAUDE_AGENTS_PATH,
+    CLAUDE_OUTPUT_STYLES_PATH,
+    CLAUDE_MCP_PATH,
+    CLAUDE_PLUGINS_PATH,
+];
+export const CLAUDE_PROFILE_MANIFEST_PATHS = [
+    CLAUDE_SETTINGS_PATH,
+    CLAUDE_SETTINGS_LOCAL_PATH,
+    CLAUDE_INSTRUCTIONS_PATH,
+    CLAUDE_COMMANDS_PATH,
+    CLAUDE_KNOWN_MARKETPLACES_PATH,
+    CLAUDE_INSTALLED_PLUGINS_PATH,
+];
+export const joinClaudeHomePath = (relativePath) => `$HOME/${relativePath}`;
+export const joinClaudeLocalPath = (localHome, relativePath) => `${localHome}/${relativePath}`;

package/dist/agents/codex.js

@@ -0,0 +1,228 @@
+import { collectEnvRefs } from "../core/env.js";
+import { MCP_STARTUP_TIMEOUT_SEC } from "../core/mcp-timeout.js";
+import { buildCodexPreSeedScript } from "../core/sandbox-scripts.js";
+import { basename } from "../core/paths.js";
+import { parse, stringify } from "smol-toml";
+import { makeVersionParser, sortNewest } from "./shared.js";
+const codexId = (file) => {
+    const match = file.match(/rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-(.+)\.jsonl$/);
+    if (!match)
+        throw new Error(`Invalid Codex transcript filename ${file}`);
+    return match[1];
+};
+const parseVersion = makeVersionParser("codex");
+const readRecordedCwd = (deps, path) => {
+    const text = deps.readFile(path);
+    if (text === null)
+        return null;
+    const first = text.split("\n", 1)[0];
+    try {
+        const parsed = JSON.parse(first);
+        return typeof parsed.payload?.cwd === "string" ? parsed.payload.cwd : null;
+    }
+    catch {
+        return null;
+    }
+};
+const isTomlTable = (value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof Date);
+const toTomlTable = (value, path) => {
+    if (value === undefined)
+        return undefined;
+    if (!isTomlTable(value))
+        throw new Error(`Expected ${path} to be a table`);
+    return value;
+};
+const toTomlString = (value, path) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`Expected ${path} to be a string`);
+    return value;
+};
+const toTomlStringArray = (value, path) => {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error(`Expected ${path} to be an array`);
+    return value.map((item, index) => {
+        if (typeof item !== "string")
+            throw new Error(`Expected ${path}[${index}] to be a string`);
+        return item;
+    });
+};
+const toTomlStringRecord = (value, path) => {
+    const table = toTomlTable(value, path);
+    if (table === undefined)
+        return undefined;
+    return Object.fromEntries(Object.entries(table).map(([key, field]) => {
+        if (typeof field !== "string")
+            throw new Error(`Expected ${path}.${key} to be a string`);
+        return [key, field];
+    }));
+};
+const collectEnvRefsFromValue = (refs, value) => {
+    if (typeof value === "string")
+        for (const name of collectEnvRefs(value))
+            refs.add(name);
+    else if (Array.isArray(value))
+        for (const item of value)
+            collectEnvRefsFromValue(refs, item);
+    else if (isTomlTable(value))
+        for (const item of Object.values(value))
+            collectEnvRefsFromValue(refs, item);
+};
+const readTomlEnvRefs = (text) => {
+    const refs = new Set();
+    const parsed = parse(text);
+    const mcpServers = toTomlTable(parsed.mcp_servers, "mcp_servers");
+    if (mcpServers !== undefined)
+        for (const [name, value] of Object.entries(mcpServers)) {
+            const server = toTomlTable(value, `mcp_servers.${name}`);
+            if (server === undefined)
+                throw new Error(`Expected mcp_servers.${name}`);
+            const env = toTomlTable(server.env, `mcp_servers.${name}.env`);
+            if (env !== undefined)
+                for (const key of Object.keys(env))
+                    refs.add(key);
+        }
+    for (const value of Object.values(parsed))
+        collectEnvRefsFromValue(refs, value);
+    return [...refs].sort();
+};
+const toMcpServer = (name, value) => {
+    const table = toTomlTable(value, `mcp_servers.${name}`);
+    if (table === undefined)
+        throw new Error(`Expected mcp_servers.${name}`);
+    const command = toTomlString(table.command, `mcp_servers.${name}.command`);
+    const args = toTomlStringArray(table.args, `mcp_servers.${name}.args`);
+    const cwd = toTomlString(table.cwd, `mcp_servers.${name}.cwd`);
+    const url = toTomlString(table.url, `mcp_servers.${name}.url`);
+    const env = toTomlStringRecord(table.env, `mcp_servers.${name}.env`);
+    return {
+        name,
+        transport: url === undefined ? "stdio" : "http",
+        ...(command === undefined ? {} : { command }),
+        ...(args === undefined ? {} : { args }),
+        ...(cwd === undefined ? {} : { cwd }),
+        ...(url === undefined ? {} : { url }),
+        ...(env === undefined ? {} : { env }),
+    };
+};
+const parseMcpServers = (deps, cwd) => {
+    const files = [
+        `${deps.home}/.codex/config.toml`,
+        `${cwd}/.codex/config.toml`,
+    ];
+    const servers = new Map();
+    for (const file of files) {
+        const text = deps.readFile(file);
+        if (text === null)
+            continue;
+        const parsed = parse(text);
+        const mcpServers = toTomlTable(parsed.mcp_servers, "mcp_servers");
+        if (mcpServers === undefined)
+            continue;
+        for (const [name, value] of Object.entries(mcpServers))
+            servers.set(name, toMcpServer(name, value));
+    }
+    return [...servers.values()].filter((server) => server.command !== undefined || server.url !== undefined);
+};
+const formatMcpConfig = (servers) => {
+    const mcpServers = {};
+    for (const server of servers) {
+        const table = { startup_timeout_sec: MCP_STARTUP_TIMEOUT_SEC };
+        if (server.command !== undefined)
+            table.command = server.command;
+        if (server.args !== undefined)
+            table.args = server.args;
+        if (server.cwd !== undefined)
+            table.cwd = server.cwd;
+        if (server.url !== undefined)
+            table.url = server.url;
+        if (server.env !== undefined)
+            table.env = server.env;
+        mcpServers[server.name] = table;
+    }
+    return {
+        path: "$HOME/.codex/config.toml",
+        content: `${stringify({ mcp_servers: mcpServers })}\n`,
+        mode: "append",
+    };
+};
+const authEnv = (deps) => {
+    const authJson = deps.readFile(`${deps.home}/.codex/auth.json`);
+    const envs = {};
+    const apiKey = deps.env.OPENAI_API_KEY;
+    if (apiKey !== undefined)
+        envs.OPENAI_API_KEY = apiKey;
+    const codexApiKey = deps.env.CODEX_API_KEY;
+    if (codexApiKey !== undefined)
+        envs.CODEX_API_KEY = codexApiKey;
+    if (authJson !== null && authJson.trim().length > 0)
+        return {
+            envs,
+            files: [{ path: "$HOME/.codex/auth.json", content: authJson }],
+        };
+    const codexHome = `${deps.home}/.codex`;
+    if (deps.exists(codexHome)) {
+        const account = `cli|${deps.sha256Hex(deps.realpath(codexHome)).slice(0, 16)}`;
+        const keychainJson = deps.keychain("Codex Auth", account);
+        if (keychainJson !== null && keychainJson.trim().length > 0)
+            return {
+                envs,
+                files: [{ path: "$HOME/.codex/auth.json", content: keychainJson }],
+            };
+    }
+    if (Object.keys(envs).length > 0)
+        return { envs, files: [] };
+    throw new Error("No Codex credential at ~/.codex/auth.json, OS keychain, OPENAI_API_KEY, or CODEX_API_KEY");
+};
+export const CODEX = {
+    id: "codex",
+    pkg: "@openai/codex",
+    bin: "codex",
+    detectVersionArgs: ["--version"],
+    parseVersion,
+    matchSession: (deps, cwd) => {
+        const root = `${deps.home}/.codex/sessions`;
+        return sortNewest(deps, deps
+            .walk(root)
+            .filter((path) => /rollout-.*\.jsonl$/.test(path))
+            .filter((path) => readRecordedCwd(deps, path) === cwd)
+            .map((path) => {
+            const name = basename(path);
+            return {
+                sessionId: codexId(name),
+                transcriptPath: path,
+                transcriptName: name,
+            };
+        }));
+    },
+    profilePaths: () => [
+        ".codex/config.toml",
+        ".codex/AGENTS.md",
+        ".codex/instructions.md",
+        ".codex/prompts",
+        ".codex/rules",
+    ],
+    mcpConfigPaths: (home, cwd) => [
+        `${home}/.codex/config.toml`,
+        `${cwd}/.codex/config.toml`,
+    ],
+    mcpEnvRefs: readTomlEnvRefs,
+    parseMcpServers,
+    formatMcpConfig,
+    authEnv,
+    installCmd: (version) => `npm i -g @openai/codex@${version}`,
+    supportsSettingsScripts: () => false,
+    supportsReinstall: () => false,
+    preSeed: (remoteProj) => [
+        "mkdir -p $HOME/.codex",
+        `node -e ${JSON.stringify(buildCodexPreSeedScript(remoteProj))}`,
+    ],
+    remoteTranscriptPath: (remoteEnc, transcriptName) => `$HOME/.codex/sessions/restored/${transcriptName}`,
+    resumeCmd: (sessionId, remoteProj) => `cd "${remoteProj}" && codex resume ${sessionId}`,
+};

package/dist/agents/index.js

@@ -0,0 +1,19 @@
+import { CLAUDE_CODE } from "./claude-code.js";
+import { CODEX } from "./codex.js";
+export const AGENTS = [CLAUDE_CODE, CODEX];
+export const detectAgents = (host, cwd) => AGENTS.filter((agent) => agent.matchSession(host, cwd).length > 0);
+export const pickAgent = (id) => {
+    for (const agent of AGENTS)
+        if (agent.id === id)
+            return agent;
+    throw new Error(`Unknown agent ${id}`);
+};
+export const selectDefaultAgent = (agents) => {
+    const claude = agents.find((agent) => agent.id === "claude-code");
+    if (claude)
+        return claude;
+    const first = agents[0];
+    if (!first)
+        throw new Error("No Claude Code or Codex session found");
+    return first;
+};

package/dist/agents/shared.js

@@ -0,0 +1,7 @@
+export const sortNewest = (deps, refs) => [...refs].sort((a, b) => deps.statMtimeMs(b.transcriptPath) - deps.statMtimeMs(a.transcriptPath));
+export const makeVersionParser = (label) => (output) => {
+    const match = output.match(/(\d+\.\d+\.\d+)/);
+    if (!match)
+        throw new Error(`Could not parse ${label} version from "${output}"`);
+    return match[1];
+};