totopo 3.0.0 → 3.0.1-rc-2

package/README.md

@@ -2,7 +2,7 @@
 
 <img src=".github/assets/logo.png" alt="totopo" width="100%" />
 
-Run AI coding agents in a secure local sandbox.
+Local sandbox for AI agents.
 
 ![build](https://github.com/asafratzon/totopo/actions/workflows/build.yml/badge.svg)
 ![tests](https://github.com/asafratzon/totopo/actions/workflows/tests.yml/badge.svg)
@@ -10,28 +10,50 @@ Run AI coding agents in a secure local sandbox.
 ![npm downloads](https://img.shields.io/npm/dm/totopo)
 ![license](https://img.shields.io/npm/l/totopo)
 
-## Why totopo?
+## Motivation
 
-AI agents are non-deterministic. They occasionally get things wrong. Most of the time they're fine — but "most of the time" isn't a great argument for giving an agent unrestricted access to your machine, your credentials, and your remote repositories.
+Two fundamental issues with AI agents:
+- They are non-deterministic — they will occasionally get things wrong.
+- They are susceptible to prompt injection — they can get compromised and act against your interests without you knowing.
 
-totopo draws a clear boundary: agents get a full, capable environment to work in — they just can't touch anything outside the workspace, and they can't reach your remote. No domain whitelisting, no paranoia, no compromise on what the agent can actually do.
+totopo addresses both with a dev container - when you run totopo in a given directory, the directory is mounted as a workspace where agents get a full, capable environment to work in — they just can't touch anything outside the workspace, and they can't reach remote git repositories.
+
+If an agent makes a mistake, damage is contained to the workspace; your git remote is out of reach.<br>
+If an agent gets compromised, it can't reach your host files — blast radius is limited to the workspace you chose to share.
+
+> totopo's security approach is basic — it is about the minimal precautions I believe anyone running AI agents should have. If you need more robust protections, look somewhere else.
 
 ## Requirements
 
 - [Docker](https://www.docker.com/products/docker-desktop/) — builds and runs the dev container
 - [Node.js](https://nodejs.org/) — required to run `npx totopo`
 
-## Getting Started
+## Quick Start
 
 ```bash
 cd your-project
 npx totopo
 ```
 
-`npx totopo` always runs the latest stable version — no install required. Alternatively, install globally to pin a specific version: `npm install -g totopo`.
+`npx totopo` always runs the latest stable version. Alternatively, install globally to pin a specific version: `npm install -g totopo`.
 
 > **Do not install totopo as a local project dependency.** totopo stores all workspace state in `~/.totopo/`, shared across all your workspaces. A local install means different projects could run different versions, which can break schema compatibility with shared config. Use `npx` or a global install.
 
+### Basic Usage
+
+Once set up, the flow is simple:
+
+1. Run `npx totopo` → **Open session**
+2. Run `claude`, `opencode`, or `codex` — pick an agent, start working
+
+A few things happen automatically:
+
+- **Agents stay up to date** — when you open a session, totopo ensures all AI CLIs are on their latest version.
+- **Sessions are persistent** — agent memory and settings survive container restarts and rebuilds.
+- **Your machine stays safe** — the container can't push to remote, can't read outside the workspace, and sensitive paths like `.env` can be hidden from agents entirely (see [Shadow Paths](#shadow-paths)).
+
+For a deeper look at how totopo works and how to configure it, see the sections below.
+
 ## How totopo Works
 
 totopo organises work around **workspaces** — any directory containing a `totopo.yaml` file. Running `npx totopo` for the first time in a directory walks you through a short setup and creates `totopo.yaml` (a small, well-documented config file that lives at the workspace root).
@@ -51,7 +73,7 @@ On every run, totopo shows the workspace menu:
 
 ### Working directory
 
-The workspace is always mounted at `/workspace` inside the container. When you run totopo from a subdirectory, you get a quick prompt to start **here** or at the **Workspace root**. If you're already at the workspace root, the session starts directly at `/workspace`.
+The workspace is always mounted at `/workspace` inside the container. When you run totopo from a subdirectory, you get a quick prompt to start **here** or at the **workspace root**. If you're already at the workspace root, the session starts directly at `/workspace`.
 
 ## Core Features
 

package/bin/totopo.js

@@ -15,7 +15,7 @@ import { run as globalMenu } from "../dist/commands/global.js";
 import { run as menu } from "../dist/commands/menu.js";
 import { run as onboard } from "../dist/commands/onboard.js";
 import { resetImage, stop, run as workspaceMenu } from "../dist/commands/workspace.js";
-import { repairTotopoYaml } from "../dist/lib/totopo-yaml.js";
+import { GITHUB_README_URL, repairTotopoYaml } from "../dist/lib/totopo-yaml.js";
 import { deriveContainerName, findTotopoYamlDir, listWorkspaceIds, resolveWorkspace } from "../dist/lib/workspace-identity.js";
 
 // --- Guard: inside container -------------------------------------------------------------------------------------------------------------
@@ -176,6 +176,9 @@ while (showMenu) {
             if (result === "back") showMenu = true;
             break;
         }
+        case "help":
+            log.info(`Check out the official docs at:\n  ${GITHUB_README_URL}`);
+            break;
         default:
             break;
     }

package/dist/commands/global.js

@@ -9,7 +9,6 @@ import { cancel, confirm, isCancel, log, multiselect, outro, select, text } from
 import { AGENTS_DIR, CONTAINER_NAME_PREFIX, LABEL_MANAGED, TOTOPO_DIR, TOTOPO_YAML } from "../lib/constants.js";
 import { safeRmSync } from "../lib/safe-rm.js";
 import { listWorkspaces } from "../lib/workspace-identity.js";
-import { run as runDoctor } from "./doctor.js";
 // --- Helpers -----------------------------------------------------------------------------------------------------------------------------
 /** Remove workspace cache dir and optionally totopo.yaml from the workspace root. Exported for testing. */
 export function removeWorkspaceFiles(workspaceRoot, workspaceDir, removeTotopoYaml) {
@@ -249,7 +248,6 @@ export async function run(currentWorkspaceId) {
                 { value: "stop-containers", label: "Stop containers", hint: "pick running containers" },
                 { value: "clear-memory", label: "Clear agent memory", hint: "pick workspaces to clear" },
                 { value: "remove-images", label: "Remove images", hint: "pick images to remove" },
-                { value: "doctor", label: "Doctor", hint: "check Docker health" },
                 { value: "uninstall-workspace", label: "Uninstall workspaces", hint: "pick workspaces to remove" },
                 { value: "uninstall", label: "Uninstall totopo", hint: "wipe ~/.totopo/ and all containers/images" },
                 { value: "back", label: "← Back" },
@@ -274,16 +272,9 @@ export async function run(currentWorkspaceId) {
                     return undefined;
                 break;
             }
-            case "doctor":
-                await runDoctor(null, true);
-                await sleep(500);
-                break;
             case "uninstall":
                 await uninstallTotopo();
                 return undefined;
         }
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/dist/commands/menu.js

@@ -27,6 +27,7 @@ export async function run(args) {
         ...(workspaceRunning ? [{ value: "stop", label: "Stop container", hint: "stops this workspace's container" }] : []),
         { value: "settings", label: "Manage Workspace", hint: "profiles, shadow paths, rebuild" },
         { value: "manage-totopo", label: "Manage totopo →", hint: "stop, clear, remove, uninstall" },
+        { value: "help", label: "Help", hint: "official docs" },
         { value: "quit", label: "Quit" },
     ];
     const action = await select({ message: "Menu:", options });

package/dist/lib/totopo-yaml.js

@@ -79,6 +79,7 @@ export function readTotopoYaml(dir) {
 // We rely on that tag existing so these URLs resolve correctly for every installed version.
 const { version } = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
 const GITHUB_RAW_BASE = `https://raw.githubusercontent.com/asafratzon/totopo/v${version}`;
+export const GITHUB_README_URL = `https://github.com/asafratzon/totopo/blob/v${version}/README.md`;
 const YAML_HEADER = `# yaml-language-server: $schema=${GITHUB_RAW_BASE}/schema/totopo.schema.json
 `;
 // Inline comments injected before specific YAML keys (preceded by a blank line)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totopo",
-  "version": "3.0.0",
+  "version": "3.0.1-rc-2",
   "description": "Run AI coding agents safely in your local codebase",
   "type": "module",
   "bin": {