@zhn2605/topo 0.1.0 → 0.3.0

package/README.md

@@ -1,50 +1,112 @@
 # Topo
 
-**AI speed, human reasoning.** Topo maps your codebase as a graph of blocks (files, classes, functions, methods). Use it to understand an area before you change it, and to review an AI agent's change on the same map: what changed, what depends on it, and what's risky, instead of scrolling a flat diff.
+**AI speed, human reasoning.** Topo draws your codebase as a map of blocks (files, classes, functions, methods) and the calls between them. Use it for two things:
 
-It works with any agent and any editor: it only reads git. Clicking a block opens it in your own editor at the right line.
+- **Before a change:** see how an area works (what runs first, what it calls, who depends on it) without reading every file.
+- **After an agent's change:** review it on the same map. What changed, what depends on it, and what's risky, ranked, instead of scrolling a flat diff.
 
-> Status: early. TypeScript/JavaScript, Luau (Roblox), Python and Rust.
+It works with any agent and any editor. It only reads git, and clicking a block opens it in your own editor at the right line.
 
-## What you get
-
-- **Change map:** changed blocks (added, modified, deleted, signature changed) as the roots of the view, with dependents shaded by distance (blast radius).
-- **Structural diff:** renames detected as renames, signature changes shown old → new, and new or removed call edges ("`checkout` now calls `db.query`").
-- **Risk-ordered queue:** each changed block gets a score with plain reasons ("7 dependents (4 direct)", "public signature changed", "1 uncertain edge").
-- **Honest edges:** calls resolved by the TypeScript type checker are solid; dynamic dispatch and inferred edges are dashed.
-- **Flow view:** entry point on the left, callees to the right in the order the code calls them, loops marked ↻. Each block shows its first 8 callees, with the rest behind "+N more".
-- **Trimmed by default:** files nearly everything imports (config, shared types, a network wrapper) are hidden and listed as "also uses: Config, Net" instead. Tests are hidden too.
-- **Lenses:** switch between *How it runs*, *Who uses this*, *Dependencies*, *Change impact* and *Unfiltered*, or define your own (below).
-- **Your layout sticks:** drag blocks where you want them; positions are saved per view in `.topo/layout.json`.
-- **Depth navigation:** search (`/`), depth, callers/callees, per-branch expand/collapse, re-rooting with breadcrumbs and back/forward.
+> Early, and moving fast. Languages: TypeScript/JavaScript, Luau (Roblox), Python, Rust, C/C++.
 
 ## Quick start
 
-Requires Node 26+ and pnpm.
+Needs Node 24+ and git.
+
+```sh
+npx @zhn2605/topo map .            # explore the repo you're in
+npx @zhn2605/topo review main      # review your changes against main
+```
+
+Or install it once and use `topo`:
+
+```sh
+npm i -g @zhn2605/topo
+topo map .
+```
+
+Both open the map in your browser. Everything runs locally; the server only listens on 127.0.0.1.
+
+## Using the map
+
+- **Press ⌘K or `/`** for the one box that does everything: type a name to jump to a block, a word to find an action (switch the view, show layers, reset the layout), or a question to ask Topo ("how does checkout work?").
+- **Right-click a block** for what you can do with it: open in your editor, make it the root, show what it calls or who calls it, ask about it.
+- **Switch views** with the button in the map's corner: *How it runs* (entry point to callees, in call order), *Who uses this*, *Dependencies*, *Change impact*, *Unfiltered*.
+- **The left panel** lists entry points (or, when reviewing, the changes ordered by risk), territories and agent activity. Fold it away or drag its edge to resize.
+- **Agent requests** come in under the bell at the top right. Requests stay until you approve or deny them; news fades after a few seconds.
+- **Drag blocks** where you want them. Your layout is saved per view in `.topo/layout.json`.
+
+## What it shows
+
+- **Changes as the starting point:** added, modified, deleted and signature-changed blocks, with everything that depends on them shaded by distance.
+- **A structural diff:** renames shown as renames, signatures old → new, and new or removed calls ("`checkout` now calls `db.query`").
+- **Risk with reasons:** each change gets a score you can read: "7 dependents (4 direct)", "public signature changed", "1 uncertain edge".
+- **Honest edges:** calls the type checker resolved are solid lines; inferred or dynamic ones are dashed.
+- **Less noise by default:** files nearly everything imports (config, shared types, a network wrapper) and tests are hidden, listed as "also uses: Config, Net" instead.
+
+## Commands
 
 ```sh
-pnpm install
-pnpm --filter @topo/web build
-
-# in any git repo with TypeScript code:
-pnpm topo diff main --repo /path/to/repo      # change list in the terminal
-pnpm topo review main --repo /path/to/repo    # opens the map in your browser
-pnpm topo graph /path/to/repo                 # graph summary (--json for the full graph)
-pnpm topo map /path/to/repo                   # explore how a program works, no diff needed
+topo map [path]              # explore a codebase (no git needed)
+topo review <base>           # review the working tree (or --head <ref>) against a branch or commit
+topo diff <base>             # the change list in the terminal (--markdown for a PR comment)
+topo graph [path]            # graph summary (--json for the full graph)
+topo export <base>           # the review map as one HTML file that opens from disk
+topo layers --suggest        # draft .topo/layers.json from your folders
+topo hook                    # print a Claude Code hook so your agent's edits show up live
 ```
 
-`--head <ref>` compares against a branch or commit instead of the working tree. `--repo` may point at a subfolder of a git repo (one game in a monorepo, say). `--lens <name>` opens with a lens. Set the editor with `--editor "nvim +{line} {file}"` or `TOPO_EDITOR` (default `code -g {file}:{line}`).
+`--repo` points at another repo, or a subfolder of one (one game in a monorepo, say). `--lens <name>` opens with a view. Set your editor with `--editor "nvim +{line} {file}"` or `TOPO_EDITOR` (default `code -g {file}:{line}`). Run `topo <command> --help` for the rest.
 
 ## Languages
 
-- **TypeScript / JavaScript:** the TypeScript 7 type checker resolves calls. One project per `tsconfig.json`, so monorepo path aliases resolve.
-- **Luau / Lua (Roblox):** tree-sitter finds functions and call sites. Requires are resolved by [`luau-lsp`](https://github.com/JohnnyMorganz/luau-lsp) with your Rojo project (`@game/...` aliases included) when it's installed (e.g. via rokit), else relative requires only. `*.server.luau` / `*.client.luau` scripts are the entry points.
-- **Python:** tree-sitter finds functions, classes and methods; calls resolve through scope, `self.`, and `import` / `from … import` (src layouts and monorepo packages found from `__init__.py`). Untyped `obj.method()` calls are left out rather than guessed.
-- **Rust:** tree-sitter plus the module tree: `mod`, `use` trees (re-exports and globs), `crate::`/`super::`, `Type::f`, `Self::`/`self.` in impls, `impl Trait for Type`. In a Tauri app, the frontend's `invoke("name")` links to the `#[tauri::command] fn name`.
+- **TypeScript / JavaScript:** the TypeScript 7 type checker resolves calls, one project per `tsconfig.json`, so monorepo path aliases work.
+- **Luau / Lua (Roblox):** tree-sitter finds functions and calls. Requires resolve through [`luau-lsp`](https://github.com/JohnnyMorganz/luau-lsp) and your Rojo project (`@game/...` aliases included) when it's installed, for example with rokit; otherwise relative requires only. `*.server.luau` and `*.client.luau` scripts are the entry points.
+- **Python:** functions, classes and methods; calls resolve through scope, `self.` and imports (src layouts and monorepo packages included). Untyped `obj.method()` calls are left out rather than guessed.
+- **Rust:** the module tree (`mod`, `use` with re-exports and globs, `crate::`, `super::`), `Type::f`, `self.` in impls, and `impl Trait for Type`. In a Tauri app, the frontend's `invoke("name")` links to its `#[tauri::command]`.
+- **C / C++:** functions, classes and methods (a header declaration and its `Type::m` definition are one block). Calls resolve through `this`, `Ns::f`, constructors, and `obj.m()` when `obj`'s type is known; free functions through the `#include` closure. Virtual dispatch, function pointers and macros are left out. Build, vendor and generated files are skipped.
+
+## Ask Topo and agents
+
+If the `claude` CLI is on your PATH, questions in the ⌘K box go to Topo's own Claude Code process. It can only use Topo's map tools, so it answers questions, changes the view and makes territories, but never edits code. Ask "how does X work" and it shows a walkthrough: the blocks that matter, numbered in the order they run, as a guided tour. Its length follows the question: a handful of steps for the gist, every step when you ask for all of it. The map glides to each block in turn, a marker travels the call that leads there, and a card under the block says what happens in it (← / → or Play to move on, Esc to leave; "Tour this walkthrough" in ⌘K starts it again). The card switches the map between *Just these blocks* and *With neighbours*, the same blocks with what they call and what calls them. Without `claude`, the box falls back to plain search.
+
+The Ask Topo panel opens on a short welcome until you close it: *Walk me through these changes* (or *how this runs* on a map), *How does … work?* and *Plan a change to …*. Asked on the review map, "walk me through this" tours the changes on that map, with a few sentences per block on what it does and what changed. A plan comes back as steps on the map and territories with their tasks written out; no agent starts until you say go.
+
+When a request could go more than one way ("split this repo up for a few agents": how many, split by what?), Topo asks first, the way Claude Code does: a question or two with choices as buttons under its reply, plus a box for your own answer. Pick and it carries on.
+
+When reviewing, **Tour the changes** (the button on the *To review* tab, or ⌘K) plays the same tour on the review map itself, over the changes it shows, callers before what they call; *Tour all N* on the card takes in every change. Each card shows what changed: the risk and its reasons, the signature old → new, calls gained and lost, the agent's reason if it gave one, and Viewed / Ask for changes. Esc brings you back to the review. Asking Topo "walk me through the change" does the same with a sentence per step.
+
+**Viewed** marks a changed block as seen, so a long review keeps your place: *To review* dims it and counts how many you've viewed, and the mark clears itself if the block changes again (after an agent's next pass you re-read only what's new). Marks are yours alone, saved in `.topo/reviews.json`, which Topo gitignores. **Ask for changes** sends a note on that block straight to the agent that made it; on a block no agent made, it reads *Hand to an agent* and starts a worker with your note as the task.
+
+**Territories** are regions of the map you hand an agent: a label, the task, and the blocks it covers (saved in `.topo/territories.json`). *Launch* starts an agent CLI headless on that task with Topo's tools, and its edits show up on the map as it makes them. Edits outside its territory aren't blocked, just flagged. Agents working in git worktrees (Claude Code subagents, Codex, `git worktree add`) show up too.
+
+**Which agents.** Launch works with any of these that are on your PATH; each territory picks one under *Runs with*:
+
+| Agent | Asks you mid-run | Continue a run | Edits on the map from |
+|---|---|---|---|
+| Claude Code (`claude`) | yes, as cards under the bell | yes | its PostToolUse hook |
+| Gemini CLI (`gemini`) | no: runs in its own sandbox (`auto_edit`; *Never ask* = `yolo`) | no | its JSON stream |
+| Codex (`codex`) | no: runs in its own sandbox (`workspace-write`; *Never ask* = bypass) | yes | its JSON stream |
+
+Ask Topo (the ⌘K box's agent) needs Claude Code; without it the box is plain search. Model overrides: `TOPO_WORKER_MODEL` (Claude, default `sonnet`), `TOPO_GEMINI_MODEL`, `TOPO_CODEX_MODEL`.
+
+**Keys are yours.** Topo never asks for, stores or sees an API key. Each CLI signs in the way it normally does: `claude` with your Claude login or `ANTHROPIC_API_KEY`, `gemini` with `GEMINI_API_KEY` or a Google login, `codex` with `codex login`. Set that up once in the CLI and Topo's launches use it.
+
+**Permissions.** The top of the Territories tab (or ⌘K, *Agent permissions*) sets what launched agents may do without asking: *Allow safe commands* (the default: reading, searching, editing, and read-only commands like `ls`, `cat`, `grep` and `git log`), *Ask for every command*, or *Never ask*. For Claude Code, anything else comes to you as a card under the bell. *Always allow* on a card saves the same rule Claude Code's own "don't ask again" saves, in the repo's `.claude/settings.local.json`, so it holds when you run `claude` yourself too. Gemini and Codex can't ask mid-run, so the setting picks their sandbox mode instead. The choice is saved in `.topo/settings.json` and applies to the next launch. Starting Topo with `--dangerously-skip-permissions` means *Never ask* for that session; the UI shows a red pill whenever nothing asks.
+
+### Connect your own agent (MCP)
+
+A running `topo map` or `topo review` serves the same map over MCP, so your agent can ask it instead of grepping:
+
+```sh
+claude mcp add --transport http topo http://127.0.0.1:4477/mcp
+```
+
+Tools include `find`, `callers`, `callees`, `blast_radius`, `get_block`, `view`, `get_layers`, `get_territory`, `request_territory` and `report_change`. The HTTP and live-events API is documented in [docs/api.md](https://github.com/zhn2605/topo/blob/mvp/docs/api.md).
 
 ## Lenses
 
-A lens is a saved view: which edges to follow, which way, how deep, what to hide. Add your own in `.topo/lenses.json` at the repo root. A lens with a built-in's name replaces it:
+A lens is a saved view: which edges to follow, which way, how deep, what to hide. Add your own in `.topo/lenses.json`; one with a built-in's name replaces it.
 
 ```json
 {
@@ -60,35 +122,11 @@ A lens is a saved view: which edges to follow, which way, how deep, what to hide
 }
 ```
 
-`view` takes `hopKinds` (`calls`, `references`, `imports`, `inherits`, `implements`), `direction` (`out`, `in`, `both`), `globalDepth`, `hiddenTags`, `excludePaths` (globs) and `containerRoots`/`foldNested`. Node ids are `path#Qualified.name` (use search, then *Properties*, to find one). Because it's a plain file, you can ask your coding agent to write a lens for the task at hand.
-
-## Agents (MCP)
-
-`topo review` and `topo map` also serve the live graph over MCP, so a coding agent can ask the map instead of grepping:
-
-```sh
-claude mcp add --transport http topo http://127.0.0.1:4477/mcp
-```
-
-Tools: `find` (search blocks by name), `callers`/`callees` (who calls or is called, to a depth), `blast_radius` (everything that depends on a block), `get_block` (kind, file:lines, signature, doc, source), `view` (apply a lens and get a text outline), `shape_view` (propose a lens for the human to see, optionally saving it to `.topo/lenses.json`), `list_territories`/`get_territory`, `request_territory` (ask for one), `report_change` (explain an edit, one sentence).
-
-Territories are regions of the map you hand an agent — a label, a note (the task), and the blocks it covers — stored in `.topo/territories.json` and editable from the UI. An agent can read its territory with `get_territory`; edits outside it aren't blocked, just flagged in the map as out-of-territory.
-
-## Command bar, agents, and the inbox
-
-The command bar (the UI's search box, also `POST /api/command {text, context?}`) is a semantic helper: it's its own headless Claude Code process, restricted to Topo's own MCP tools (`--tools ""`, `--strict-mcp-config`), so it can change the view, focus blocks, make or update territories, launch or stop agents, and decide inbox items — but it never edits code. Without a `claude` CLI on PATH, it falls back to a plain block search.
-
-Launching an agent on a territory (the UI's "Launch" button, also `POST /api/territories/<id>/launch`) starts a real headless `claude -p` in your repo, scoped to that territory's task. It gets Topo's MCP tools over `--mcp-config`, and Topo writes it the same PostToolUse hook `topo hook` prints (via `--settings`) so its edits are attributed in the map without you pasting anything — it works the same way in any repo. `GET /api/runs` lists runs; `POST /api/runs/<id>/stop` stops one.
-
-The inbox (`GET /api/inbox`, `POST /api/inbox/<id> {decision: "approve"|"deny"|"dismiss"}`) is everything waiting on you: an agent asking for a territory or a permission, a proposed view, or an FYI (it finished, it stepped outside its territory, two agents touched the same block). The UI surfaces it as a queue; deciding an item unblocks the agent that's waiting on it.
-
-Agents working in git worktrees (Claude Code subagents in `.claude/worktrees/`, Codex, `git worktree add`) show up too: their hook's file path is mapped onto the served checkout, the edited blocks are found by diffing the worktree's copy, and the agent's label carries the worktree's name.
-
-Start the server with `--dangerously-skip-permissions` to have launched agents skip every permission prompt (like Claude Code's flag of the same name); the UI shows a red pill while it's on.
+`view` takes `hopKinds` (`calls`, `references`, `imports`, `inherits`, `implements`), `direction` (`out`, `in`, `both`), `globalDepth`, `hiddenTags`, `excludePaths` (globs) and `containerRoots`/`foldNested`. Block ids look like `path#Qualified.name`; find one with ⌘K, then *Properties* in the Inspector. It's a plain file, so you can ask your agent to write a lens for the task at hand.
 
 ## Layers and boundary rules
 
-`topo layers --suggest` drafts `.topo/layers.json` from your top-level source folders (one level into `packages/`, `apps/` and so on). Rename and merge them, then add rules by hand:
+`topo layers --suggest` drafts `.topo/layers.json` from your top-level folders, or ask Topo to "sort this code into layers". Rename and merge them, then add rules:
 
 ```json
 { "version": 1,
@@ -96,15 +134,11 @@ Start the server with `--dangerously-skip-permissions` to have launched agents s
   "rules": [{ "from": "client", "notTo": "server", "why": "talk through Net remotes" }] }
 ```
 
-Reviews then flag every *new* call or import that crosses a rule: a risk reason on the block, a "Boundary crossings" section in the PR comment, and `topo diff <base> --fail-on-violations` exits 1 for CI. Existing crossings aren't flagged, so an old codebase doesn't light up on day one.
-
-## Using Topo from other tools
-
-Topo is a layer other tools call, not a platform that competes with them. A running `topo map` serves a versioned HTTP + live-events + MCP API (`GET /api/meta` → `api: 1`); see [docs/api.md](docs/api.md).
+With layers, blocks are colored by layer, *Group by layer* draws each layer as a region, and *Overview* shows the whole program as one box per layer with the calls between them. Reviews flag every *new* call that breaks a rule (existing ones aren't, so an old codebase doesn't light up on day one), and `topo diff <base> --fail-on-violations` exits 1 for CI.
 
 ## On pull requests (GitHub Action)
 
-`topo diff <base> --markdown` prints a PR comment: the riskiest changed blocks with their reasons, shared hubs touched, and signature changes. `topo export <base>` writes the review map as one HTML file that opens from disk. The action at this repo's root runs both on each PR, keeps one comment up to date, and links the map from it (as a run artifact):
+The action posts one PR comment, kept up to date, with the riskiest changes and their reasons, shared code touched, signature changes and boundary crossings, and links the full map as a run artifact:
 
 ```yaml
 on: pull_request
@@ -123,25 +157,16 @@ jobs:
 ```
 git repo ──► indexer (TS checker / tree-sitter) ──► graph (base + head)
                                               │
-git diff ──► hunks ──► identity matching ──► graph diff ──► blast radius + risk ──► review UI
+git diff ──► hunks ──► identity matching ──► graph diff ──► blast radius + risk ──► map
 ```
 
-The base version is extracted from git into a cache keyed by commit SHA, so your working tree is never touched. Everything runs locally; the server binds to 127.0.0.1.
-
-## Accuracy
-
-Graph accuracy is measured, not assumed. `node packages/engine/src/eval/run.ts` indexes a hand-labeled fixture repo and reports precision and recall per edge kind; CI fails if call-edge accuracy regresses.
+The base version is extracted from git into a cache keyed by commit, so your working tree is never touched. Graph accuracy is measured against a hand-labeled fixture repo, and CI fails if call-edge accuracy drops.
 
-## Development
-
-```sh
-pnpm test        # vitest
-pnpm typecheck
-pnpm lint        # biome
-pnpm --filter @topo/web dev   # UI dev server; open /?mock for sample data
-```
+## Changes
 
-Layout: `packages/engine` (indexer, diff, identity, graph diff, core views, analysis, eval), `packages/cli` (the `topo` command and local server), `apps/web` (React UI).
+- **0.3.0:** Ask Topo hands code changes to a worker agent itself; Launch runs Gemini CLI and Codex as well as Claude Code; agent permissions (safe commands by default, *Always allow* on a request card); a badge on every block an agent is editing; guided tours of walkthroughs, and *Tour the changes* in a review; repeat "outside its territory" warnings fold into one card; *Viewed* and *Ask for changes* replace Approve and Request changes (saved across restarts, cleared when a block changes again, notes go straight to the agent).
+- **0.2.0:** a new interface: one ⌘K box for search, actions and questions; right-click menus on blocks; views as one list; a single side panel you can fold or resize; agent requests under a bell with Approve/Deny on each card; quieter colors. Runs on Node 24+ (was 26+).
+- **0.1.0:** first preview.
 
 ## License