totopo 0.8.0 → 0.9.0-rc-2

package/README.md

@@ -8,15 +8,15 @@ Spin up a secure, isolated AI coding environment in any git project — in one c
 
 ## How It Works
 
-`npx totopo` sets up a hardened Docker container in your project with AI coding assistants (Claude, Kilo, OpenCode) pre-installed. Your code stays on your host machine. The AI tools run isolated inside the container.
+`npx totopo` sets up a hardened Docker container in your project with AI coding assistants (OpenCode, Claude Code, Codex) pre-installed. Your code stays on your host machine. The AI tools run isolated inside the container.
 
 ```
 Host machine
 ├── your editor       → edits files normally (bind-mounted from container)
 ├── terminal          → connected to container via docker exec
-│   ├── claude        → AI tools run here, isolated
-│   ├── kilo
-│   └── opencode
+│   ├── opencode      → AI tools run here, isolated
+│   ├── claude
+│   └── codex
 └── git push/pull     → only possible from host, blocked inside container
 ```
 
@@ -74,9 +74,9 @@ your-project/
 Run inside the container terminal:
 
 ```bash
-claude      # Claude Code (Anthropic)
-kilo        # Kilo AI
 opencode    # OpenCode
+claude      # Claude Code (Anthropic)
+codex       # Codex (OpenAI)
 status      # Re-run security + readiness check
 ```
 
@@ -90,7 +90,7 @@ status      # Re-run security + readiness check
 | Filesystem isolation     | Only the repo is mounted — host is not visible                                                    |
 | Git remote block         | `protocol.allow never` in `/etc/gitconfig` — enforced at the git layer, requires root to override |
 | No privilege escalation  | `no-new-privileges:true` security opt                                                             |
-| Secrets never in image   | API keys injected at runtime via `.env` only                                                      |
+| Secrets never in image   | API keys loaded at runtime from `~/.totopo/.env` — never baked into the image, never mounted into the container |
 
 Remote git operations are blocked inside the container. Push from your host terminal instead.
 

package/bin/totopo.js

@@ -5,7 +5,7 @@
 // =============================================================================
 
 import { execSync, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -60,9 +60,7 @@ const { run: onboard } = await import("../dist/commands/onboard.js");
 const { run: menu } = await import("../dist/commands/menu.js");
 const { run: dev } = await import("../dist/commands/dev.js");
 const { run: stop } = await import("../dist/commands/stop.js");
-const { run: rebuild } = await import("../dist/commands/rebuild.js");
-const { run: manage } = await import("../dist/commands/manage.js");
-const { run: settings } = await import("../dist/commands/settings.js");
+const { run: advanced } = await import("../dist/commands/advanced.js");
 
 // ─── Onboarding ───────────────────────────────────────────────────────────────
 if (!existsSync(`${repoRoot}/.totopo/Dockerfile`)) {
@@ -98,29 +96,12 @@ const projectRunning = (projectContainerResult.stdout ?? "")
     .filter(Boolean)
     .some((n) => n === `totopo-managed-${projectName}`);
 
-const projectImageResult = spawnSync("docker", ["images", "-q", `totopo-managed-${projectName}`], { encoding: "utf8" });
-const projectImageExists = (projectImageResult.stdout ?? "").trim().length > 0;
-
-let hasKey = false;
-const envPath = `${repoRoot}/.totopo/.env`;
-if (existsSync(envPath)) {
-    for (const line of readFileSync(envPath, "utf8").split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith("#")) continue;
-        const value = trimmed.slice(trimmed.indexOf("=") + 1).trim();
-        if (value) {
-            hasKey = true;
-            break;
-        }
-    }
-}
-
 // ─── Interactive menu loop ────────────────────────────────────────────────────
 let showMenu = true;
 while (showMenu) {
     showMenu = false;
 
-    const action = await menu({ projectName, activeCount, hasKey, projectRunning, projectImageExists });
+    const action = await menu({ projectName, activeCount, projectRunning });
 
     switch (action) {
         case "dev":
@@ -129,20 +110,8 @@ while (showMenu) {
         case "stop":
             await stop(projectName);
             break;
-        case "rebuild":
-            await rebuild(projectName);
-            await dev(packageDir, repoRoot);
-            break;
-        case "manage": {
-            const result = await manage(projectName, repoRoot);
-            if (result === "back") showMenu = true;
-            break;
-        }
-        case "doctor":
-            await doctor(repoRoot, true);
-            break;
-        case "settings": {
-            const result = await settings(packageDir, repoRoot);
+        case "advanced": {
+            const result = await advanced(packageDir, projectName, repoRoot);
             if (result === "back") showMenu = true;
             break;
         }

package/dist/commands/advanced.js

@@ -0,0 +1,207 @@
+// =========================================================================================================================================
+// src/core/commands/advanced.ts — Advanced submenu
+// Invoked by bin/totopo.js — do not run directly.
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { cancel, confirm, isCancel, log, multiselect, outro, select } from "@clack/prompts";
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function stopAndRemoveContainer(name) {
+    spawnSync("docker", ["stop", name], { stdio: "inherit" });
+    spawnSync("docker", ["rm", name], { stdio: "inherit" });
+}
+// ─── Clear agent memory ───────────────────────────────────────────────────────
+async function clearAgentMemory(projectName, totopoDir) {
+    const containerName = `totopo-managed-${projectName}`;
+    // Check if the container is running
+    const inspectResult = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", containerName], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    const isRunning = inspectResult.status === 0 && inspectResult.stdout.trim() === "running";
+    if (isRunning) {
+        const confirmed = await confirm({
+            message: `The dev container for ${projectName} is running. It must be stopped to clear agent memory. Continue?`,
+        });
+        if (isCancel(confirmed) || !confirmed) {
+            cancel("Cancelled.");
+            return;
+        }
+        log.step(`Stopping ${containerName}...`);
+        stopAndRemoveContainer(containerName);
+    }
+    const agentsDir = join(totopoDir, "agents");
+    if (existsSync(agentsDir)) {
+        rmSync(agentsDir, { recursive: true, force: true });
+    }
+    log.success("Agent memory cleared. Context will be regenerated on next session start.");
+}
+// ─── Stop containers ──────────────────────────────────────────────────────────
+async function stopContainers() {
+    const listResult = spawnSync("docker", ["ps", "--filter", "name=totopo-managed-", "--format", "{{.Names}}"], {
+        encoding: "utf8",
+    });
+    const running = (listResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    if (running.length === 0) {
+        log.info("No running totopo containers.");
+        return;
+    }
+    let toStop;
+    if (running.length === 1) {
+        toStop = running;
+        log.info(`Stopping ${running[0]}...`);
+    }
+    else {
+        const selected = await multiselect({
+            message: "Select containers to stop:",
+            options: running.map((name) => ({ value: name, label: name })),
+            required: false,
+        });
+        if (isCancel(selected)) {
+            cancel();
+            return;
+        }
+        toStop = selected;
+    }
+    for (const name of toStop) {
+        log.step(`Stopping ${name}...`);
+        stopAndRemoveContainer(name);
+    }
+    log.success("Done.");
+}
+// ─── Remove images ────────────────────────────────────────────────────────────
+async function removeImages() {
+    const listResult = spawnSync("docker", ["images", "--filter", "label=totopo.managed=true", "--format", "{{.Repository}}\t{{.ID}}"], {
+        encoding: "utf8",
+    });
+    const lines = (listResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    if (lines.length === 0) {
+        log.info("No totopo images found.");
+        return;
+    }
+    const images = lines.map((line) => {
+        const [repo, id] = line.split("\t");
+        const workspace = (repo ?? "").replace(/^totopo-managed-/, "");
+        return { repo: repo ?? "", id: id ?? "", workspace };
+    });
+    const selected = await multiselect({
+        message: "Select images to remove:",
+        options: images.map((img) => ({
+            value: img.repo,
+            label: `${img.workspace}  (${img.repo})`,
+        })),
+        required: false,
+    });
+    if (isCancel(selected)) {
+        cancel();
+        return;
+    }
+    for (const repo of selected) {
+        // Stop any running container using this image first
+        const psResult = spawnSync("docker", ["ps", "--filter", `name=${repo}`, "--format", "{{.Names}}"], {
+            encoding: "utf8",
+        });
+        const containers = (psResult.stdout ?? "").trim().split("\n").filter(Boolean);
+        for (const c of containers) {
+            log.step(`Stopping container ${c} before removing image...`);
+            stopAndRemoveContainer(c);
+        }
+        log.step(`Removing image ${repo}...`);
+        spawnSync("docker", ["rmi", repo], { stdio: "inherit" });
+    }
+    log.success("Done.");
+}
+// ─── Uninstall ────────────────────────────────────────────────────────────────
+async function uninstall(projectName, repoRoot) {
+    const containerName = `totopo-managed-${projectName}`;
+    const imageName = `totopo-managed-${projectName}`;
+    const confirmed = await confirm({
+        message: `Remove .totopo/, stop containers, and delete the image for ${projectName}?`,
+    });
+    if (isCancel(confirmed) || !confirmed) {
+        cancel();
+        return;
+    }
+    const inspectResult = spawnSync("docker", ["inspect", "--type", "container", containerName], { encoding: "utf8" });
+    if (inspectResult.status === 0) {
+        log.step(`Stopping container ${containerName}...`);
+        stopAndRemoveContainer(containerName);
+    }
+    const imageResult = spawnSync("docker", ["images", "-q", imageName], { encoding: "utf8" });
+    if ((imageResult.stdout ?? "").trim().length > 0) {
+        log.step(`Removing image ${imageName}...`);
+        spawnSync("docker", ["rmi", imageName], { stdio: "inherit" });
+    }
+    log.step("Removing .totopo/...");
+    rmSync(join(repoRoot, ".totopo"), { recursive: true, force: true });
+    outro("Uninstalled. Re-run npx totopo to set up again.");
+}
+// ─── Reset API keys ───────────────────────────────────────────────────────────
+async function resetApiKeys(packageDir) {
+    const globalEnvPath = join(homedir(), ".totopo", ".env");
+    const confirmed = await confirm({
+        message: `Reset ${globalEnvPath}? This affects all totopo projects on this machine.`,
+    });
+    if (isCancel(confirmed) || !confirmed) {
+        cancel("Cancelled.");
+        return;
+    }
+    mkdirSync(join(homedir(), ".totopo"), { recursive: true });
+    cpSync(join(packageDir, "templates", "env"), globalEnvPath);
+    log.success(`API keys reset. Edit ${globalEnvPath} to add your keys.`);
+}
+// ─── Advanced submenu ─────────────────────────────────────────────────────────
+export async function run(packageDir, projectName, repoRoot) {
+    // Dynamic imports to avoid circular deps — same pattern as bin/totopo.js
+    const { run: runSettings } = await import("./settings.js");
+    const { run: runRebuild } = await import("./rebuild.js");
+    const { run: runDoctor } = await import("./doctor.js");
+    const totopoDir = join(repoRoot, ".totopo");
+    while (true) {
+        const action = await select({
+            message: "Advanced:",
+            options: [
+                { value: "runtime-mode", label: "Runtime mode", hint: "switch between host-mirror and full" },
+                { value: "rebuild", label: "Rebuild container", hint: "force a fresh image build for this project" },
+                { value: "clear-memory", label: "Clear agent memory", hint: "wipe conversation history for this project" },
+                { value: "uninstall", label: "Uninstall from this project", hint: "removes .totopo/ and deletes the container and image" },
+                { value: "stop-containers", label: "Stop containers", hint: "all projects" },
+                { value: "remove-images", label: "Remove images", hint: "all projects" },
+                { value: "reset-keys", label: "Reset API keys", hint: "overwrites ~/.totopo/.env — affects all projects" },
+                { value: "doctor", label: "Doctor", hint: "check Docker and container health" },
+                { value: "back", label: "← Back" },
+            ],
+        });
+        if (isCancel(action) || action === "back") {
+            return "back";
+        }
+        switch (action) {
+            case "runtime-mode":
+                await runSettings(packageDir, repoRoot);
+                break;
+            case "rebuild":
+                await runRebuild(projectName);
+                break;
+            case "clear-memory":
+                await clearAgentMemory(projectName, totopoDir);
+                break;
+            case "reset-keys":
+                await resetApiKeys(packageDir);
+                break;
+            case "uninstall":
+                await uninstall(projectName, repoRoot);
+                return; // uninstall tears down .totopo — exit entirely
+            case "doctor":
+                await runDoctor(repoRoot, true);
+                break;
+            case "stop-containers":
+                await stopContainers();
+                break;
+            case "remove-images":
+                await removeImages();
+                break;
+        }
+    }
+}

package/dist/commands/dev.js

@@ -3,9 +3,9 @@
 // Invoked by bin/totopo.js — do not run directly.
 // =========================================================================================================================================
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, join, relative } from "node:path";
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
 import { cancel, confirm, groupMultiselect, isCancel, log, multiselect, note, outro, path, select } from "@clack/prompts";
 // ─── Prompt: scope selection ──────────────────────────────────────────────────
 async function promptScope(workspaceDir, totopoDir, cwd) {
@@ -30,8 +30,24 @@ async function promptScope(workspaceDir, totopoDir, cwd) {
             // Fallback to cwd mode when no visible items exist
             return { mode: "cwd", hostCwd: cwd, selectedPaths: [] };
         }
+        log.warn("Scoped workspace — some context may be unavailable to the agent:\n" +
+            "  · Your personal agent config files (~/.claude/CLAUDE.md, ~/.config/opencode/AGENTS.md, etc.)\n" +
+            "    are not mounted from the host — only totopo's injected context is available.\n" +
+            "  · Project-level context files (AGENTS.md, CLAUDE.md, .claude/rules/, etc.) that live\n" +
+            "    outside your mounted paths will not be visible to the agent.\n" +
+            "  · Git is unavailable — .git is not mounted in scoped mode (security boundary).\n" +
+            "  The agent has been instructed to surface its limitations at session start.");
         return { mode, hostCwd: cwd, selectedPaths };
     }
+    if (mode === "cwd") {
+        log.warn("Scoped workspace — some context may be unavailable to the agent:\n" +
+            "  · Your personal agent config files (~/.claude/CLAUDE.md, ~/.config/opencode/AGENTS.md, etc.)\n" +
+            "    are not mounted from the host — only totopo's injected context is available.\n" +
+            "  · Project-level context files (AGENTS.md, CLAUDE.md, .claude/rules/, etc.) that live\n" +
+            "    outside this directory will not be visible to the agent.\n" +
+            "  · Git is unavailable — .git is not mounted in scoped mode (security boundary).\n" +
+            "  The agent has been instructed to surface its limitations at session start.");
+    }
     return { mode, hostCwd: cwd, selectedPaths: [] };
 }
 // ─── Prompt: selective path selection ─────────────────────────────────────────
@@ -209,14 +225,31 @@ function getTotopoMountPath(scope, workspaceDir) {
         return "/workspace/.totopo";
     return "/home/devuser/.totopo";
 }
+// ─── Build agent mount args ───────────────────────────────────────────────────
+// Creates .totopo/agents/ subdirectories on the host (lazily, on first run) and
+// returns volume mount args for all supported agent tools. Each agent tool gets
+// its own read-write bind mount so session data persists across container rebuilds.
+function buildAgentMountArgs(totopoDir) {
+    const agentsDir = join(totopoDir, "agents");
+    const mounts = [
+        { host: join(agentsDir, "claude"), container: "/home/devuser/.claude" },
+        { host: join(agentsDir, "opencode", "config"), container: "/home/devuser/.config/opencode" },
+        { host: join(agentsDir, "opencode", "data"), container: "/home/devuser/.local/share/opencode" },
+        { host: join(agentsDir, "codex"), container: "/home/devuser/.codex" },
+    ];
+    for (const { host } of mounts)
+        mkdirSync(host, { recursive: true });
+    return mounts.flatMap(({ host, container }) => ["-v", `${host}:${container}`]);
+}
 // ─── Build mount args ─────────────────────────────────────────────────────────
 function buildMountArgs(scope, workspaceDir, totopoDir, cwd) {
     const totopoMount = getTotopoMountPath(scope, workspaceDir);
+    const agentMounts = buildAgentMountArgs(totopoDir);
     if (scope.mode === "repo") {
-        return ["-v", `${workspaceDir}:/workspace`];
+        return ["-v", `${workspaceDir}:/workspace`, ...agentMounts];
     }
     if (scope.mode === "cwd") {
-        return ["-v", `${cwd}:/workspace`, ...(cwd !== workspaceDir ? ["-v", `${totopoDir}:${totopoMount}:ro`] : [])];
+        return ["-v", `${cwd}:/workspace`, ...(cwd !== workspaceDir ? ["-v", `${totopoDir}:${totopoMount}:ro`] : []), ...agentMounts];
     }
     // selective: validate all paths exist first
     for (const p of scope.selectedPaths) {
@@ -226,7 +259,12 @@ function buildMountArgs(scope, workspaceDir, totopoDir, cwd) {
             process.exit(1);
         }
     }
-    return [...scope.selectedPaths.flatMap((p) => ["-v", `${join(cwd, p)}:/workspace/${p}`]), "-v", `${totopoDir}:${totopoMount}:ro`];
+    return [
+        ...scope.selectedPaths.flatMap((p) => ["-v", `${join(cwd, p)}:/workspace/${p}`]),
+        "-v",
+        `${totopoDir}:${totopoMount}:ro`,
+        ...agentMounts,
+    ];
 }
 // ─── Build scope env args ─────────────────────────────────────────────────────
 function buildScopeEnvArgs(scope) {
@@ -290,47 +328,102 @@ function scopesMatch(selected, existing, workspaceDir) {
     }
     return true;
 }
-// ─── Build agent context document ─────────────────────────────────────────────
-// Designed for future extension: also inject AGENTS.md alongside CLAUDE.md.
-function buildAgentContextDoc(scope, workspaceDir) {
+function buildAgentContextDocs(scope) {
+    // ── Scope section ──────────────────────────────────────────────────────────
     let scopeSection;
     if (scope.mode === "repo") {
         scopeSection = `## Workspace scope: repo
 
-You are running inside a totopo dev container. The full repository is accessible at \`/workspace\`. Some operations (git push, system-level changes) require running on the host.`;
+You have access to the full repository at \`/workspace\`. Some operations (git push, system-level changes) require running on the host.`;
     }
     else if (scope.mode === "cwd") {
         scopeSection = `## Workspace scope: cwd
 
-Workspace is scoped to one directory (\`${scope.hostCwd}\`). Files outside it are not visible. Commands that depend on absent files will fail.`;
+Workspace is scoped to one directory (\`${scope.hostCwd}\`). Files outside it are not visible to you. Commands that depend on absent files will fail.`;
     }
     else {
         const pathList = scope.selectedPaths.map((p) => `- \`/workspace/${p}\``).join("\n");
         scopeSection = `## Workspace scope: selective
 
-Workspace is selectively scoped. The following paths are mounted:\n\n${pathList}`;
+Workspace is selectively scoped. Only the following paths are mounted:\n\n${pathList}`;
+    }
+    // ── Git section ────────────────────────────────────────────────────────────
+    let gitSection;
+    if (scope.mode === "repo") {
+        gitSection = `## Git availability
+
+Git is fully available for local operations (commit, branch, log, diff, status, etc.).
+
+Remote access (push, pull, fetch, clone) is **blocked at the system level** by design — \`protocol.allow = never\` is enforced in \`/etc/gitconfig\` and cannot be overridden without root. This is a deliberate security boundary: the container has no access to remote repositories. Ask the user to run any remote git operations from the host.`;
+    }
+    else {
+        gitSection = `## Git availability
+
+Git local operations are **not available** in this scope — \`.git\` is not mounted. This is intentional: mounting \`.git\` would expose the full commit history of all repository files, including those outside your current mount, defeating the security boundary of scoped access.
+
+Remote access is also **blocked container-wide** by design (\`protocol.allow = never\` in \`/etc/gitconfig\`).
+
+If git operations are needed, ask the user to run them on the host.`;
     }
-    const constraintsSection = `## Constraints
+    // ── Selective-only warning ─────────────────────────────────────────────────
+    const selectiveWarning = scope.mode === "selective"
+        ? `\n\n## Selective scope: file creation warning
+
+Any file you create **outside your mounted paths** (e.g. at \`/\`, \`/tmp\`, or any path not listed above) will **not be visible on the host** and will be lost when the container is rebuilt.
+
+If the user asks you to create or modify a file at such a location:
+1. Notify the user that the path is outside your mounted workspace.
+2. Explain that files created there will not sync to the host.
+3. Suggest the user run the command on the host instead, or confirm they want the file only inside the container (understanding it will be lost on rebuild).`
+        : "";
+    // ── Responsibilities section ───────────────────────────────────────────────
+    const responsibilitiesSection = `## Your responsibilities at session start
+
+At the start of every session:
+- Briefly surface your current workspace scope and its limitations to the user.
+- Tell the user what you cannot access in this session (files, git, remotes).`;
+    // ── Assemble per-tool — only the self-referencing path differs ─────────────
+    function build(toolPath) {
+        const constraintsSection = `## Constraints
 
 - Files outside mounted paths cannot be read, written, or executed.
 - If a command fails because of missing files, tell the user: "I have limited workspace scope — please run \`<command>\` on the host."
-- This file (\`~/.claude/CLAUDE.md\`) is container-generated. Edits will not persist to the host.
-- \`.totopo/\` is read-only inside the container.`;
-    const repoClaudeMdPath = join(workspaceDir, "CLAUDE.md");
-    const baseContent = existsSync(repoClaudeMdPath) ? readFileSync(repoClaudeMdPath, "utf8").trim() : null;
-    const parts = ["# totopo Workspace Context\n\nYou are running inside a totopo dev container.\n", scopeSection, constraintsSection];
-    if (baseContent) {
-        parts.push("---\n", baseContent);
-    }
-    return `${parts.join("\n\n")}\n`;
+- \`.totopo/\` is read-only inside the container.
+- This file (\`${toolPath}\`) is managed by totopo and overwritten on every session start. Do not edit it.`;
+        return ([
+            "# totopo Workspace Context\n\nYou are running inside a totopo dev container.\n",
+            scopeSection,
+            gitSection,
+            constraintsSection,
+            responsibilitiesSection,
+        ].join("\n\n") +
+            selectiveWarning +
+            "\n");
+    }
+    return {
+        claude: build("~/.claude/CLAUDE.md"),
+        opencode: build("~/.config/opencode/AGENTS.md"),
+        codex: build("~/.codex/AGENTS.md"),
+    };
 }
-// ─── Inject agent context into container ──────────────────────────────────────
-function injectAgentContext(name, content) {
-    const tmpPath = join(tmpdir(), `totopo-claude-md-${Date.now()}.md`);
-    writeFileSync(tmpPath, content);
-    spawnSync("docker", ["exec", name, "mkdir", "-p", "/home/devuser/.claude"]);
-    spawnSync("docker", ["cp", tmpPath, `${name}:/home/devuser/.claude/CLAUDE.md`]);
-    unlinkSync(tmpPath);
+// ─── Inject agent context ─────────────────────────────────────────────────────
+// Writes context files directly to .totopo/agents/ on the host. The agent dirs
+// are created on demand (recursive mkdir) so this is safe to call on first run
+// before any directories exist, as well as on subsequent runs where it simply
+// overwrites existing files with the latest context. The agent dirs are served
+// into the container via volume mounts — no docker cp required. Called before
+// every container start/resume so context always reflects the current scope.
+function injectAgentContext(totopoDir, docs) {
+    const a = join(totopoDir, "agents");
+    const files = [
+        { path: join(a, "claude", "CLAUDE.md"), content: docs.claude },
+        { path: join(a, "opencode", "config", "AGENTS.md"), content: docs.opencode },
+        { path: join(a, "codex", "AGENTS.md"), content: docs.codex },
+    ];
+    for (const { path, content } of files) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+    }
 }
 // ─── Run post-start ───────────────────────────────────────────────────────────
 function runPostStart(name, totopoMountPath) {
@@ -348,8 +441,22 @@ function removeContainer(name) {
     spawnSync("docker", ["stop", name], { stdio: "pipe" });
     spawnSync("docker", ["rm", name], { stdio: "pipe" });
 }
+// ─── Ensure global env file exists ───────────────────────────────────────────
+// ~/.totopo/.env lives outside all project repos so it is never mounted into
+// the container and cannot be read by agents. Created empty on first run so
+// --env-file always has a valid target.
+function ensureGlobalEnvFile() {
+    const globalTotopoDir = join(homedir(), ".totopo");
+    const envFile = join(globalTotopoDir, ".env");
+    mkdirSync(globalTotopoDir, { recursive: true });
+    if (!existsSync(envFile)) {
+        writeFileSync(envFile, "");
+    }
+    return envFile;
+}
 // ─── Run container ────────────────────────────────────────────────────────────
 function runContainer(scope, containerName, imageName, workspaceDir, totopoDir, cwd) {
+    const envFile = ensureGlobalEnvFile();
     const run = spawnSync("docker", [
         "run",
         "-d",
@@ -357,7 +464,7 @@ function runContainer(scope, containerName, imageName, workspaceDir, totopoDir,
         containerName,
         ...buildMountArgs(scope, workspaceDir, totopoDir, cwd),
         "--env-file",
-        `${workspaceDir}/.totopo/.env`,
+        envFile,
         ...buildScopeEnvArgs(scope),
         ...buildScopeLabelArgs(scope),
         "--security-opt",
@@ -396,10 +503,10 @@ export async function run(_packageDir, repoRoot) {
             process.exit(build.status ?? 1);
         }
         const totopoMountPath = getTotopoMountPath(scope, repoRoot);
+        log.step("Preparing agent context...");
+        injectAgentContext(totopoDir, buildAgentContextDocs(scope));
         log.step("Starting dev container...");
         runContainer(scope, containerName, imageName, repoRoot, totopoDir, cwd);
-        log.step("Injecting agent context...");
-        injectAgentContext(containerName, buildAgentContextDoc(scope, repoRoot));
         runPostStart(containerName, totopoMountPath);
     }
     else if (containerStatus === "exited") {
@@ -407,22 +514,22 @@ export async function run(_packageDir, repoRoot) {
         const existingScope = readContainerScopeLabel(containerName);
         const totopoMountPath = getTotopoMountPath(scope, repoRoot);
         if (scopesMatch(scope, existingScope, repoRoot)) {
+            log.step("Preparing agent context...");
+            injectAgentContext(totopoDir, buildAgentContextDocs(scope));
             log.step("Resuming dev container...");
             const start = spawnSync("docker", ["start", containerName], { stdio: "inherit" });
             if (start.status !== 0) {
                 outro("Failed to start dev container.");
                 process.exit(start.status ?? 1);
             }
-            log.step("Injecting agent context...");
-            injectAgentContext(containerName, buildAgentContextDoc(scope, repoRoot));
             runPostStart(containerName, totopoMountPath);
         }
         else {
+            log.step("Preparing agent context...");
+            injectAgentContext(totopoDir, buildAgentContextDocs(scope));
             log.step("Recreating dev container with new scope...");
             removeContainer(containerName);
             runContainer(scope, containerName, imageName, repoRoot, totopoDir, cwd);
-            log.step("Injecting agent context...");
-            injectAgentContext(containerName, buildAgentContextDoc(scope, repoRoot));
             runPostStart(containerName, totopoMountPath);
         }
     }
@@ -431,14 +538,19 @@ export async function run(_packageDir, repoRoot) {
         const existingScope = readContainerScopeLabel(containerName);
         if (!scopesMatch(scope, existingScope, repoRoot)) {
             const totopoMountPath = getTotopoMountPath(scope, repoRoot);
+            log.step("Preparing agent context...");
+            injectAgentContext(totopoDir, buildAgentContextDocs(scope));
             log.step("Recreating dev container with new scope...");
             removeContainer(containerName);
             runContainer(scope, containerName, imageName, repoRoot, totopoDir, cwd);
-            log.step("Injecting agent context...");
-            injectAgentContext(containerName, buildAgentContextDoc(scope, repoRoot));
             runPostStart(containerName, totopoMountPath);
         }
-        // same scope — connect directly (fall through)
+        else {
+            // Same scope and container already running — refresh context in place.
+            log.step("Refreshing agent context...");
+            injectAgentContext(totopoDir, buildAgentContextDocs(scope));
+        }
+        // fall through to connect
     }
     // ─── Connect ──────────────────────────────────────────────────────────────────
     const exec = spawnSync("docker", ["exec", "-it", "-w", "/workspace", containerName, "bash", "--login"], {

package/dist/commands/menu.js

@@ -4,28 +4,22 @@
 // =========================================================================================================================================
 import { box, cancel, isCancel, select } from "@clack/prompts";
 export async function run(args) {
-    const { projectName, activeCount, projectRunning, projectImageExists } = args;
-    // ─── Status box ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+    const { projectName, activeCount, projectRunning } = args;
+    // ─── Status box ──────────────────────────────────────────────────────────────
     const containersLabel = activeCount === 0 ? "none" : activeCount === 1 ? "1 running" : `${activeCount} running`;
-    const lines = [];
-    lines.push(`workspace:   ${projectName}`);
-    lines.push(`containers:  ${containersLabel}`);
-    box(lines.join("\n"), " totopo ", {
+    box(`workspace:   ${projectName}\ncontainers:  ${containersLabel}\nkeys:        ~/.totopo/.env`, " totopo ", {
         contentAlign: "center",
         titleAlign: "center",
         width: "auto",
         rounded: true,
     });
-    // ─── Menu ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+    // ─── Menu ─────────────────────────────────────────────────────────────────────
     const action = await select({
         message: "Menu:",
         options: [
-            { value: "dev", label: "Start session" },
-            ...(projectRunning ? [{ value: "stop", label: "Stop" }] : []),
-            ...(projectImageExists ? [{ value: "rebuild", label: "Rebuild" }] : []),
-            { value: "settings", label: "Settings" },
-            { value: "manage", label: "Manage workspaces" },
-            { value: "doctor", label: "Doctor" },
+            { value: "dev", label: "Open session", hint: "start or resume the dev container" },
+            ...(projectRunning ? [{ value: "stop", label: "Stop dev container", hint: "stops this project's container" }] : []),
+            { value: "advanced", label: "Advanced", hint: "rebuild, memory, settings, and more" },
             { value: "quit", label: "Quit" },
         ],
     });

package/dist/commands/onboard.js

@@ -3,6 +3,7 @@
 // Invoked by bin/totopo.js when no .totopo/ config is found in the project.
 // =========================================================================================================================================
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { box, cancel, confirm, intro, isCancel, log, outro, select } from "@clack/prompts";
 import { writeSettings } from "../lib/config.js";
@@ -31,6 +32,7 @@ export async function run(packageDir, repoRoot) {
     mkdirSync(totopoDir, { recursive: true });
     cpSync(join(templatesDir, "Dockerfile"), join(totopoDir, "Dockerfile"));
     cpSync(join(templatesDir, "post-start.mjs"), join(totopoDir, "post-start.mjs"));
+    cpSync(join(templatesDir, "README.md"), join(totopoDir, "README.md"));
     log.success("Copied config templates to .totopo/");
     // ─── Runtime mode ────────────────────────────────────────────────────────────
     const modeChoice = await select({
@@ -66,14 +68,17 @@ export async function run(packageDir, repoRoot) {
         return false;
     }
     const commitScope = scopeChoice;
-    // ─── Create .env ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-    const envPath = join(totopoDir, ".env");
-    if (existsSync(envPath)) {
-        log.info(".totopo/.env already exists — leaving it untouched");
+    // ─── Create global .env ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+    // ~/.totopo/.env lives outside all project repos — never mounted into containers, never readable by agents.
+    const globalTotopoDir = join(homedir(), ".totopo");
+    const globalEnvPath = join(globalTotopoDir, ".env");
+    mkdirSync(globalTotopoDir, { recursive: true });
+    if (existsSync(globalEnvPath)) {
+        log.info(`${globalEnvPath} already exists — leaving it untouched`);
     }
     else {
-        cpSync(join(templatesDir, "env"), envPath);
-        log.success("Created .totopo/.env");
+        cpSync(join(templatesDir, "env"), globalEnvPath);
+        log.success(`Created ${globalEnvPath}`);
     }
     // ─── Gitignore ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
     const gitignorePath = join(repoRoot, ".gitignore");
@@ -91,18 +96,20 @@ export async function run(packageDir, repoRoot) {
         }
     }
     else {
-        const entry = ".totopo/.env";
-        const addition = "\n# totopo — API keys must never be committed\n.totopo/.env\n";
-        if (gitignoreContent?.includes(entry)) {
-            log.info(".totopo/.env already in .gitignore");
+        const agentsEntry = ".totopo/agents/";
+        let content = gitignoreContent ?? "";
+        if (gitignoreContent?.includes(agentsEntry)) {
+            log.info(".totopo/agents/ already in .gitignore");
         }
         else {
-            const newContent = gitignoreContent !== null ? gitignoreContent + addition : addition;
-            writeFileSync(gitignorePath, newContent);
-            log.success("Added .totopo/.env to .gitignore");
+            content += "\n# totopo — agent session data is local only\n.totopo/agents/\n";
+            log.success("Added .totopo/agents/ to .gitignore");
+        }
+        if (content !== (gitignoreContent ?? "")) {
+            writeFileSync(gitignorePath, content);
         }
     }
-    log.info("Optionally add API keys to .totopo/.env before starting the container.");
+    log.info(`Add API keys to ${globalEnvPath} before starting the container.`);
     outro("Setup complete.");
     return true;
 }

package/dist/lib/generate-dockerfile.js

@@ -34,7 +34,7 @@ function buildHostMirrorDockerfile(selectedTools, host) {
     sections.push(`# =============================================================================
 # Secure AI Dev Container — host-mirror mode
 # =============================================================================
-# Non-root user, no git remote access, AI tools: claude, kilo, opencode
+# Non-root user, no git remote access, AI tools: opencode, claude, codex
 # Runtimes: selected by totopo host-mirror (regenerated on each session start)
 # =============================================================================
 
@@ -147,9 +147,9 @@ RUN git config --system protocol.allow never && \
 # ---------------------------------------------------------------------------
 RUN npm install -g \
     pnpm \
-    @anthropic-ai/claude-code \
-    @kilocode/cli \
     opencode-ai \
+    @anthropic-ai/claude-code \
+    @openai/codex \
     && npm cache clean --force`);
     // ── Layer 10 — Non-root user ─────────────────────────────────────────────
     sections.push(String.raw `# ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totopo",
-  "version": "0.8.0",
+  "version": "0.9.0-rc-2",
   "description": "Secure AI Box — isolated dev environments for AI coding assistants",
   "type": "module",
   "bin": {

package/templates/Dockerfile

@@ -1,7 +1,7 @@
 # =============================================================================
 # Secure AI Dev Container — General-purpose multi-stack
 # =============================================================================
-# Non-root user, no git remote access, AI tools: claude, kilo, opencode
+# Non-root user, no git remote access, AI tools: opencode, claude, codex
 # Runtimes: Node.js, Python, Go, Rust, Java (Temurin 21), Bun
 # =============================================================================
 
@@ -93,9 +93,9 @@ RUN git config --system protocol.allow never && \
 # ---------------------------------------------------------------------------
 RUN npm install -g \
     pnpm \
-    @anthropic-ai/claude-code \
-    @kilocode/cli \
     opencode-ai \
+    @anthropic-ai/claude-code \
+    @openai/codex \
     && npm cache clean --force
 
 # ---------------------------------------------------------------------------

package/templates/README.md

@@ -0,0 +1,76 @@
+# .totopo — Reference
+
+Created by `npx totopo`. Manages the secure dev container for this project.
+
+---
+
+## Files
+
+| File             | Purpose                                                    |
+| ---------------- | ---------------------------------------------------------- |
+| `Dockerfile`     | Builds the container image                                 |
+| `post-start.mjs` | Runs on every start — security checks + readiness summary  |
+| `settings.json`  | Runtime mode + selected tools (committed with project)     |
+| `agents/`        | Agent session data — created on first session start        |
+
+---
+
+## agents/
+
+Initialised automatically the first time you run a dev session. Contains
+per-tool subdirectories for each supported agent, mounted into the container
+so session history and conversation data persist across rebuilds:
+
+```
+agents/claude/           → ~/.claude/                    (Claude Code)
+agents/opencode/config/  → ~/.config/opencode/           (OpenCode)
+agents/opencode/data/    → ~/.local/share/opencode/
+agents/codex/            → ~/.codex/                     (Codex)
+```
+
+Context files (`CLAUDE.md` / `AGENTS.md`) are written into these directories
+by totopo on every session start and overwritten automatically — do not edit them.
+
+`agents/` is gitignored — session data stays local to this machine.
+
+To reset agent memory: **Advanced → Clear agent memory** from the totopo menu.
+
+---
+
+## Security model
+
+- **Non-root user** (`devuser`, uid 1001) — cannot modify system-level config
+- **Git remote access blocked** via `protocol.allow = never` in `/etc/gitconfig` — push, pull, fetch, and clone are all refused; local operations work normally
+- **No host credentials forwarded** — host git credentials are never copied into the container
+- **API keys passed at runtime** via `--env-file ~/.totopo/.env` — never baked into the image and never mounted into the container
+- **No privilege escalation** — `no-new-privileges:true` prevents any process from gaining elevated permissions
+
+---
+
+## AI tools
+
+| Command    | Package                     |
+| ---------- | --------------------------- |
+| `opencode` | `opencode-ai`               |
+| `claude`   | `@anthropic-ai/claude-code` |
+| `codex`    | `@openai/codex`             |
+
+Tools are installed during image build. To update a tool version: edit `Dockerfile`,
+then use **Advanced → Rebuild container** from the totopo menu.
+
+---
+
+## Startup check
+
+`post-start.mjs` runs on every container start and validates:
+
+1. Running as non-root
+2. Git remote block active in `/etc/gitconfig`
+3. `git push` functionally blocked
+4. All AI tools installed and reachable
+
+Re-run manually anytime from inside the container:
+
+```bash
+status
+```

package/templates/env

@@ -1,19 +1,30 @@
 # =============================================================================
 # totopo — API Keys
 # =============================================================================
-# Fill in your keys before starting the container.
-# Add .totopo/.env to your project's .gitignore — keys must never be committed.
+#
+# WARNING: This file is loaded into every totopo container at runtime via
+# --env-file. It lives at ~/.totopo/.env on your host machine and is never
+# mounted into the container filesystem — agents cannot read it directly.
+#
+# However, treat this file as sensitive. Do not commit it, do not share it,
+# and do not paste it into agent sessions. If you believe a key has been
+# exposed, rotate it immediately from your provider's dashboard.
 # =============================================================================
 
-# Anthropic (Claude Code — optional if using Pro subscription via browser auth)
-ANTHROPIC_API_KEY=
+# OpenAI — GPT models, used by OpenCode and Codex
+OPENAI_API_KEY=
 
-# Kilo AI
-KILO_API_KEY=
+# Anthropic — Claude models, used by Claude Code and OpenCode
+ANTHROPIC_API_KEY=
 
-# OpenCode supports multiple providers — add whichever you use
-OPENAI_API_KEY=
+# Google — Gemini models
 GEMINI_API_KEY=
 
-# Optional: OpenRouter (gives access to many models via one key)
+# xAI — Grok models
+XAI_API_KEY=
+
+# Groq — fast inference for open models (Llama, Mixtral, etc.)
+GROQ_API_KEY=
+
+# OpenRouter — unified gateway to 200+ models from multiple providers
 OPENROUTER_API_KEY=

package/templates/post-start.mjs

@@ -77,9 +77,9 @@ const checkTool = (cmd) => {
     }
 };
 
-checkTool("claude");
-checkTool("kilo");
 checkTool("opencode");
+checkTool("claude");
+checkTool("codex");
 
 // ─── Runtimes ────────────────────────────────────────────────────────────────
 section("Runtimes");