# Agent Canvas
Source: https://docs.nogic.dev/features/agent-canvas
Ask AI on the canvas; answers come back as interactive diagrams
Nogic's Agent Canvas lets an AI client (Claude Code or Codex) answer questions by drawing diagrams on the visualizer canvas instead of generating prose. It's powered by a [local MCP server](/mcp/overview) that exposes canvas-rendering tools the AI can call.
**Works in any language.** The AI client reads your code with its own native `Read` / `Glob` / `Grep` tools, so `Cmd+K` works in Rust, Go, Java, Ruby, C++, or anything else, even though Nogic's [code graph](/features/visualizer) only parses JS / TS / Python today. The one exception is `render_code_tour` (high verbosity), which targets indexed symbols and so requires a parsed language.
## The Director cursor
Press `Cmd+K` (or `Ctrl+K`) inside the visualizer. The on-canvas **Director cursor** opens an input bubble. Type a question, hit enter, and Nogic streams your prompt to the active CLI.
The cursor handles:
* Streaming narration from the AI as it works
* Auto-zooming to whatever the AI focuses on
* Walking through narrative steps one at a time (Next / Previous)
* Continuing the conversation: a second `Cmd+K` reuses the prior turn so you can drill in (`"Now show me the error path"`)
Conversations idle out after 30 minutes; after that, the next `Cmd+K` starts fresh.
## What the AI can render
The canvas supports several diagram families. The AI picks whichever fits the question best:
| Diagram | Best for |
| ------------------------------------------ | ------------------------------------------------------------------- |
| **Generic tree** (`render` / `patch`) | Architecture overviews, component hierarchies, free-form layouts |
| **Dataflow** (`render_dataflow`) | Pipelines, request flows, fan-out / fan-in patterns |
| **Sequence** (`render_sequence`) | Request/response order, protocols, actor handshakes |
| **State machine** (`render_state_machine`) | Lifecycles, auth flows, retry/error transitions |
| **ER diagram** (`render_er_diagram`) | Database schemas and table relationships |
| **Code tour** (`render_code_tour`) | High-verbosity walks through real files / symbols in your workspace |
Each render comes with a step-by-step **narrative**. The cursor advances through steps, focusing the relevant primitives and reading the rationale. Patch tools (`patch`, `patch_dataflow`, `patch_sequence`, `patch_state_machine`) let the AI extend an existing diagram instead of redrawing it, useful for follow-up questions that drill into one piece.
See the [MCP overview](/mcp/overview) for the full tool surface.
## Verbosity & follow-ups
The cursor settings expose a verbosity dropdown:
* **Auto / low / medium**: concise diagrams, narrative-driven explanations
* **High**: switches to `render_code_tour`, which walks through real workspace symbols step by step with per-step rationale
You can also pick which CLI handles the turn (Claude Code vs Codex) and which model tier (`auto`, `cheap`, `medium`) directly from the cursor.
A second `Cmd+K` reuses the same conversation so follow-ups feel natural:
> "Walk me through how the auth flow works."
> *(diagram appears)*
> "Now show me what happens when the token is expired."
> *(diagram extends with the error path via patch ops)*
## Saving walkthroughs
Walkthroughs the AI generates are saved per workspace under `~/.nogic/workspaces//saved_walkthroughs/`. They survive between sessions so you can revisit the answer without re-asking.
Saved walkthroughs are wiped once on extension upgrade if their payload shape changed. The on-canvas history is preserved, but new conversations start fresh.
## Privacy considerations
Your prompts and the AI's tool calls go to whichever CLI you've configured (Claude Code or Codex). Nogic itself doesn't proxy or log them. The MCP server only exposes canvas-rendering tools; it never reads source files or sends them anywhere. Workspace files the AI reads come through the CLI's own native `Read` / `Glob` / `Grep` tools, governed by the CLI's permission model.
## Next
Get `Cmd+K` working with Claude Code
Get `Cmd+K` working with Codex
# Diff Analyze
Source: https://docs.nogic.dev/features/diff-analyze
Read changed code with risk levels, blast radius, and connection arrows
Diff Analyze turns a diff into a guided reading tool. Instead of summarizing the diff for you, it shows the actual code, reordered intelligently, classified by change type, with visible connections to the rest of the codebase and a blast-radius score for every file.
The philosophy: **show the code with superpowers, don't replace it**.
## Opening Diff Analyze
When AI agents (Claude Code, Codex, or any client connected to the Nogic MCP server) generate a diff analysis, it loads automatically (no manual step). You can also open the surface anytime from the toolbar's **Diff** button, which shows the most recent change set and how many files it touches.
## What you see
**Smart ordering.** Files are sorted by the dependency graph, not alphabetically. New foundations appear first, then their callers, then unrelated changes, so the diff reads in the order that makes it make sense.
**Change classification.** Every change is tagged: `[NEW CODE]`, `[MODIFICATION]`, `[REFACTOR]`, `[DELETION]`. Filter to only the kinds that need careful reading.
**Connection arrows.** Each modified function shows its callers and callees inline, with click-through navigation. You can trace impact without grepping.
**Blast radius.** Every changed file gets a `LOW` / `MEDIUM` / `HIGH` impact score computed from the dependency graph. Auth middleware called by every API route lights up; an isolated utility doesn't.
**Change groups.** When a single session touches multiple unrelated areas, Nogic groups them. You read coherent slices rather than 15 random files.
**Convention checks.** Test gaps and naming-convention violations surface as findings with risk levels (safe / warning / critical).
## Diff map
The **Diff map** view visualizes which files changed and which files are impacted (callers, callees, transitive blast radius). Use it to scope your read: zoom into the high-risk subgraph first, leave low-risk leaves for last.
## Sharing
Use **Copy as Markdown** to dump the full analysis into a PR description, Slack thread, or email. The export preserves grouping, classifications, blast radius, and findings.
## Language support
Diff Analyze builds on the same parsed graph as the visualizer, so smart ordering, blast radius, change groups, and connection arrows light up for **JS / TS / Python**. Files in other languages still show up in the diff with classification tags, but they don't get graph-based scoring.
## How it stays fast
All analysis runs locally:
* **Smart ordering, classification, connections, blast radius, grouping** are pure graph + AST analysis on the same index that powers the visualizer
* **AI** is used only for naming change groups and explaining *why* a change matters
About 80% of the value lands without an AI roundtrip. Diff Analyze opens instantly even on large branches.
## Tuning cost & speed
Two settings control the AI authoring trade-offs. Defaults are tuned for Claude Pro/Max and Codex Plus/Pro — most users won't need to touch them.
* **`nogic.diffAnalyze.modelTier`** (`cheap` | `medium`, default `medium`) — quality vs cost. `medium` uses Sonnet / codex-grade for reliable diagrams; `cheap` cuts cost \~3-5× by using Haiku / mini at the expense of multi-file diagram quality.
* **`nogic.diffAnalyze.concurrency`** (`1-16`, default `8`) — how many groups author in parallel. Higher values finish faster but multiply peak in-flight API calls. Lower if you're on Anthropic API tier 1.
See the [Reference page](/reference#diff-analyze-tuning) for when to flip each. Both take effect on the next authoring run — no restart needed.
## Stale canvases
When your code changes after a canvas was authored, Diff Analyze doesn't auto-regenerate it (that would burn tokens on every keystroke). Instead, the system tracks whether your edits fall *outside* the regions the canvas already described:
* **Inside scope** — your edit modifies code the canvas already covers. The canvas stays valid; no badge.
* **Outside scope** — you added new code in a region the canvas hadn't seen. A small **STALE** badge appears on the affected group, and a banner appears in the Context card.
When you see one or more STALE badges, the toolbar surfaces a **Refresh N stale** button — click it to re-author all stale groups in parallel. Per-group refresh is also available from the badge itself.
Edits that don't change a group's *structure* (member files + change types stay the same) reuse cached artifacts indefinitely. Reverting an edit hits the cache instantly.
## Next
The graph that powers blast-radius and dependency analysis
The tool surface AI clients use to drive Diff Analyze and the canvas
# Visualizer
Source: https://docs.nogic.dev/features/visualizer
Browse your codebase as one connected map
The visualizer is the heart of Nogic. It renders your workspace as a unified graph of files, classes, functions, and the imports/calls/types that connect them, laid out automatically with [Dagre](https://github.com/dagrejs/dagre) and rendered with [React Flow](https://reactflow.dev/).
Open it any time with **Nogic: Open Visualizer** from the Command Palette, or click the Nogic icon in the editor title bar.
## Unified view
Files, classes, functions, methods, and components live in one graph. Folders nest visually so you keep a sense of project structure while you trace connections.
* **Edge types**: imports, calls, references, type relationships, inheritance
* **Smart zoom**: distant nodes simplify to labels; details reveal as you zoom in
* **Selected nodes** stay in front so you don't lose them when zooming out
* **Auto-sync**: file changes reflect on the canvas in real time
## Search
Press `Cmd+F` (or `Ctrl+F`) inside the visualizer. The search bar handles structural lookups (filename, symbol name, partial path) and pans/zooms to the match. Search is purely structural; AI-driven "explain this" queries live behind `Cmd+K` (see [Agent Canvas](/features/agent-canvas)).
## Boards
Boards are focused, named subsets of the codebase. Use them to keep an authentication map, an API surface map, or whatever cross-section you reach for repeatedly.
**Create a board**
* Right-click any file or folder in the Explorer → **Add to Nogic Board**
* Or click **Add Files** in the visualizer (or press `Cmd+I` / `Ctrl+I`) to pick from a workspace browser
* Empty boards open straight into the file browser so you can populate them
The first folder you add auto-renames the board. New files created under folders already on a board are picked up automatically when you rescan.
Boards persist across sessions and survive layout changes. You can keep many open and switch between them without losing position.
## Inspect mode
Right-click any node and choose **Inspect** to isolate it with its directly connected nodes. The subgraph re-lays itself out for clarity, edges show at full opacity, and you can incrementally expand by right-clicking a neighbor → **Add Connected Nodes**.
Press `Esc` (or click the close button) to drop back to the full canvas.
## Layout & navigation
| Action | Shortcut |
| ----------------- | ------------------------------------------------- |
| Focus search | `Cmd+F` / `Ctrl+F` |
| Open AI cursor | `Cmd+K` / `Ctrl+K` |
| Open file browser | `Cmd+I` / `Ctrl+I` |
| Fit view | toolbar button |
| Reflow atlas | **Nogic: Reflow Atlas** (clears cached positions) |
Layout direction (LR / TB / BT / RL) and edge visibility (always / on-select / hidden) are tunable per board from the toolbar.
## Performance
The atlas handles 30k+ files. Nodes simplify automatically when zoomed out, folder collapse states are preserved per board, and the selected node always stays interactive even when its neighborhood is abstracted.
## Language support
The visualizer renders parsed symbols, so it only shows nodes for languages Nogic can parse: **JavaScript / TypeScript (including JSX/TSX) and Python**. Files in other languages still appear as leaves on the file tree, but they don't get classes, functions, or call edges.
If you work in a language Nogic doesn't parse yet, the [AI canvas](/features/agent-canvas) still works: `Cmd+K` doesn't depend on the symbol index for most diagram types.
## Privacy
All parsing, indexing, and rendering happens locally. The graph database lives at `~/.nogic/workspaces//nogic.db`. No code leaves your machine.
## Next
Drive the canvas with `Cmd+K` and AI-rendered diagrams
See risk levels and blast radius for changed code
# Introduction
Source: https://docs.nogic.dev/index
AI-powered code comprehension, inside your editor
## What is Nogic?
Nogic is an editor extension for VS Code, VSCodium, and other Code OSS-compatible IDEs, built around a single goal: **help you understand code faster**.
Press `Cmd+K` anywhere on the canvas and ask a question (*"how does authentication work here?"*, *"walk me through the request lifecycle"*, *"what happens when the token expires?"*). An AI client (Claude Code or Codex) answers by drawing the explanation. Architecture, sequence, dataflow, state machine, and ER diagrams unfold step by step, with a narrative cursor that walks you through each piece. The AI client reads your real code via its own tools, so this works **in any language**.
Nogic also turns your workspace into an interactive map of files, classes, functions, and the connections between them. The map is useful on its own for exploring, but more importantly, it's the substrate for **Diff Analyze**: changes get smart-ordered by dependency, classified, and scored by blast radius so you read the right code in the right order, not an AI summary instead of the code.
## Why Nogic?
Most AI tooling tries to summarize code for you. Summaries replace comprehension; you skim, you trust, you merge, and the codebase grows more opaque to you over time.
Nogic takes the opposite approach: **show the code with superpowers, don't summarize it**.
* AI explains code visually instead of textually: diagrams you can navigate, not paragraphs you skim
* Diff analyze surfaces *which* code deserves attention (risk, blast radius, classification) without writing the review for you
* The visualization makes structure and connections legible so you don't have to keep them in your head
You're still reading the code. Nogic just makes sure you're reading the *right* code, in the *right* order, with the *right* context.
## What you can do
`Cmd+K` and let the AI render the answer as a walkable diagram
Smart-ordered diffs with risk, blast radius, and connection arrows
Files, classes, and connections as one navigable graph
Pin the parts of the codebase you reach for repeatedly
## Privacy
Your code stays on your machine. Parsing, indexing, visualization, and the MCP server all run locally inside your editor. No code, files, or personal data is sent to external servers.
Prompts you type into `Cmd+K` go to whichever AI CLI you've configured (Claude Code or Codex). Nogic itself doesn't proxy or log them. See [nogic.dev/telemetry](https://nogic.dev/telemetry) for the (anonymous) metrics the extension does collect.
## Language support
| Surface | Languages |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **AI canvas** (`Cmd+K` cursor, render / patch / dataflow / sequence / state machine / ER) | **Any language** |
| **Code graph** (visualizer, boards, diff analyze, blast-radius, `render_code_tour`) | JavaScript / TypeScript (incl. JSX/TSX), Python |
The AI canvas works on any codebase because the AI client reads files with its own native `Read` / `Glob` / `Grep`. It doesn't need Nogic's symbol index. Press `Cmd+K` in Rust or Go and you'll still get diagrams.
The graph-backed features (visualizer view, diff analyze scoring, the high-verbosity `render_code_tour`) need parsed symbols, which today means JS / TS / Python. More languages are on the way.
## Next steps
Install the extension and ask your first question on the canvas
Set up `Cmd+K` with Claude Code
# Installation
Source: https://docs.nogic.dev/installation
Install the Nogic editor extension
## Requirements
* VS Code `1.88.0` or higher (or VSCodium / Code OSS at the same engine version)
* A workspace folder open in VS Code
That's it. There's no separate runtime or service to install. Indexing, parsing, and the MCP server all run inside the extension host.
## Install from the Marketplace
Nogic is published on both the **VS Code Marketplace** (used by VS Code) and **Open VSX** (used by Cursor, VSCodium, Windsurf, Theia, Eclipse Che, and other forks). Use whichever your editor reads from — the build is identical.
### VS Code Marketplace
1. Open VS Code
2. Open Extensions (`Cmd+Shift+X` / `Ctrl+Shift+X`)
3. Search for **Nogic** (publisher: `Nogic`)
4. Click **Install**
Or from the terminal:
```bash theme={null}
code --install-extension Nogic.nogic
```
Direct link: [marketplace.visualstudio.com/items?itemName=Nogic.nogic](https://marketplace.visualstudio.com/items?itemName=Nogic.nogic)
### Open VSX (Cursor, VSCodium, Windsurf, etc.)
VS Code forks ship without access to Microsoft's Marketplace and use Open VSX instead. The install steps are the same — open Extensions, search **Nogic**, click Install — your editor will pull from Open VSX automatically.
CLI equivalents per editor:
```bash theme={null}
cursor --install-extension Nogic.nogic # Cursor
codium --install-extension Nogic.nogic # VSCodium
windsurf --install-extension Nogic.nogic # Windsurf
```
Direct link: [open-vsx.org/extension/Nogic/nogic](https://open-vsx.org/extension/Nogic/nogic)
## Install from a `.vsix`
If you'd rather sideload a build (or you're on a Code fork that doesn't list the extension in its marketplace):
```bash theme={null}
code --install-extension nogic-.vsix
```
In VS Code: Extensions sidebar → `…` menu → **Install from VSIX…**
## Verify
After install, run **Nogic: Open Visualizer** from the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`). The visualizer panel should open and offer to index the current workspace.
## Update
VS Code auto-updates extensions by default. To force an update:
Extensions sidebar → find **Nogic** → click the gear icon → **Check for Updates**.
## Where Nogic stores data
| Path | Contents |
| ------------------------------------------------ | ---------------------------------------------------------------------- |
| `~/.nogic/workspaces//nogic.db` | The local SQLite index for each workspace |
| `~/.nogic/workspaces//saved_walkthroughs/` | Saved AI canvas walkthroughs |
| `~/.codex/config.toml` | An auto-managed `[mcp_servers.nogic]` block (only if Codex is enabled) |
Nothing is sent off your machine. To wipe Nogic's data, delete the `~/.nogic` directory (and the marker block from `~/.codex/config.toml` if you'd previously enabled Codex).
## Uninstall
Extensions sidebar → **Nogic** → gear icon → **Uninstall**.
To remove all local data:
```bash theme={null}
rm -rf ~/.nogic
```
## Next steps
Open the visualizer and explore your code
Connect Claude Code or Codex to the canvas
# Claude Code
Source: https://docs.nogic.dev/mcp/claude-code
Use Claude Code to power Nogic's AI features
The Nogic extension spawns [Claude Code](https://docs.claude.com/en/docs/claude-code) for you with the MCP server pre-wired — no manual config required.
## Prerequisites
* Your editor (VS Code or compatible) with the [Nogic extension](/installation) installed
* Claude Code installed and on your `PATH`
Verify Claude Code is installed:
```bash theme={null}
claude --version
```
If you see a version, you're set. If not, follow the [Claude Code install guide](https://docs.claude.com/en/docs/claude-code).
## Usage
1. Open the visualizer (**Nogic: Open Visualizer**)
2. The MCP Setup overlay should show **Claude Code: installed, enabled**. If not, enable the toggle.
3. Press `Cmd+K` (or `Ctrl+K`) inside the visualizer.
4. Type your question in the cursor bubble.
Behind the scenes the extension:
* Writes a temp file with `{"mcpServers": {"nogic": {"type": "http", "url": "http://127.0.0.1:.../mcp"}}}`
* Spawns `claude` with `--mcp-config ` and `--allowedTools mcp__nogic__*`
* Streams narration deltas back into the cursor as Claude calls render / patch tools
The CLI's native `Read` / `Glob` / `Grep` are also available to Claude during the turn, governed by Claude Code's normal permission model.
### Continuing a conversation
A second `Cmd+K` reuses the prior conversation (Claude Code's `--continue`) so follow-ups feel natural:
> "Walk me through how auth works."
> *(diagram appears)*
> "Now show the path when the token is expired."
> *(diagram extends)*
After 30 minutes idle, the next `Cmd+K` starts fresh.
### Switching CLI / model
The cursor lets you pick:
* **CLI**: Claude Code or Codex, per-turn override
* **Model tier**: `auto`, `cheap` (Haiku), `medium` (Sonnet), or a specific model id
* **Verbosity**: `auto`, `low`, `medium`, or `high` (switches to `render_code_tour`)
You can also set a default CLI globally:
```jsonc theme={null}
// settings.json
{
"nogic.walkthrough.preferredCli": "claude" // "auto" | "claude" | "codex"
}
```
## Troubleshooting
**`claude` not detected in the MCP Setup overlay**: make sure `claude --version` works in a normal terminal. The extension uses your shell's `PATH`. If you installed via `npm` to a custom prefix, restart VS Code so it picks up the new `PATH`.
**Tools time out / `user cancelled MCP tool call`**: the extension launches Claude Code with `--allowedTools mcp__nogic__*` to skip per-tool approval prompts. If you see this error, check that the MCP Setup overlay shows Claude Code as enabled.
**Canvas doesn't update**: the visualizer must be open for canvas tools to apply. The tool will return a clear error message ("no panel open") that Claude can recover from.
## Next
Full canvas tool reference
Same flow with Codex
# Codex
Source: https://docs.nogic.dev/mcp/codex
Use OpenAI Codex to power Nogic's AI features
[Codex](https://github.com/openai/codex) (OpenAI's CLI) is a first-class option for the visualizer cursor. Unlike Claude Code, Codex doesn't accept a per-call `--mcp-config` flag; it only reads MCP servers from `~/.codex/config.toml`. The extension manages that file for you.
## Prerequisites
* Your editor (VS Code or compatible) with the [Nogic extension](/installation) installed
* Codex installed and on your `PATH`
Verify:
```bash theme={null}
codex --version
```
## Usage
1. Open the visualizer (**Nogic: Open Visualizer**)
2. In the MCP Setup overlay, ensure **Codex** is enabled
3. Press `Cmd+K` and ask your question
When Codex is enabled, the extension writes (or updates) a managed block in `~/.codex/config.toml`:
```toml theme={null}
# === nogic-extension begin (auto-managed; do not edit) ===
[mcp_servers.nogic]
url = "http://127.0.0.1:54123/mcp"
default_tools_approval_mode = "approve"
# === nogic-extension end ===
```
The block:
* Is rewritten on **every extension activation** (the URL changes per session)
* Sets `default_tools_approval_mode = "approve"` so `codex exec` doesn't auto-cancel MCP tool calls when there's no TTY to show approval prompts
* Is removed automatically if you disable Codex in the MCP Setup overlay
* Backs up your existing config to `~/.codex/config.toml.nogic.bak` the first time it touches the file
Anything outside the markers is left alone.
## Switching CLI / model
The cursor in the visualizer exposes per-turn overrides for CLI and model tier. To set a global default:
```jsonc theme={null}
// settings.json
{
"nogic.walkthrough.preferredCli": "codex" // "auto" | "claude" | "codex"
}
```
`auto` probes both CLIs at startup and picks the first that's enabled and available (Claude Code first, Codex second).
## Disabling Codex
In the MCP Setup overlay, toggle **Codex** off. The extension immediately strips the managed block from `~/.codex/config.toml`. Re-enable any time to restore it.
You can also disable it via settings:
```jsonc theme={null}
{
"nogic.walkthrough.enabledClis": ["claude"]
}
```
## Troubleshooting
**`codex` not detected**: ensure `codex --version` works in your shell. Restart VS Code if you installed Codex after VS Code was already running.
**Tool calls fail with "user cancelled"**: the auto-managed block sets `default_tools_approval_mode = "approve"`. If you've manually edited the block (the markers protect it on rewrite, but a manual edit between markers gets overwritten), make sure that line is still there.
**Stale URL after restart**: the block is rewritten on every activation. If you opened a Codex session before VS Code finished activating, exit and restart Codex.
## Next
Full canvas tool reference
Same flow with Claude Code
# MCP Overview
Source: https://docs.nogic.dev/mcp/overview
How Nogic's local MCP server lets AI clients drive the canvas
## What is MCP?
[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open protocol that lets AI clients connect to external tools. Nogic exposes a small, focused tool surface over MCP so AI clients can render diagrams directly onto the visualizer canvas.
## Architecture
Nogic ships an MCP server **inside the extension**: there's no remote service to point at and no API key to manage. When the extension activates, the server boots on an ephemeral `127.0.0.1` port and serves [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) MCP at `/mcp`.
When you press `Cmd+K`, the extension spawns the active CLI as a subprocess with this URL pre-wired. The CLI calls render / patch tools; the MCP server routes each call to the visualizer panel; the canvas updates in place.
Third-party MCP clients (Cursor, Windsurf, etc.) aren't supported yet — the bearer token + ephemeral port rotate every restart and Nogic can't auto-rewrite their configs. Use Claude Code or Codex via `Cmd+K` for now.
The MCP port is **ephemeral**: it changes each time the extension activates. The MCP Setup overlay always shows the live URL, and Codex's config is auto-rewritten on every activation. For external Claude Code and Cursor configs, you'll need to update the URL when it changes, or use the `Cmd+K` flow which manages this for you.
## Tool surface
The MCP server is intentionally narrow. It does **not** compete with the AI client's native `Read` / `Glob` / `Grep` tools, which are faster than an HTTP roundtrip and tighter into the CLI's permission model. Nogic owns canvas mutation only.
### Generic tree canvas
#### `render`
Replace the canvas with a tree-structured spec. Use for the initial visualization or whenever the layout should change wholesale.
#### `patch`
Apply incremental changes (add/remove/move nodes, set props, set status, modify connections). Prefer over `render` once a base spec is on screen.
#### `set_narrative`
Install a step-by-step walkthrough. Each step focuses primitives, optionally reveals/hides nodes, sets the camera, and narrates.
#### `focus`
Drive the on-canvas cursor to a primitive by id without reflowing the canvas.
### Dataflow
#### `render_dataflow`
Render a code-flow / pipeline / sequence diagram in the dedicated dataflow style: clean Dagre TB layout, simple shape nodes (cylinder for stores, box for services, circle for entry/exit), per-step active-pair box. Best for sequential pipelines and fan-out / convergence patterns.
#### `patch_dataflow`
Incrementally extend an active dataflow canvas: add new nodes (children, callees, sub-steps), wire them with edges, append narrative steps. Used for follow-up drill-ins.
### Sequence
#### `render_sequence`
Render a UML-style sequence diagram: lifelines (service / database / external) with activity boxes and message arrows. Best for "what is the request/response order?", "show me the protocol" questions.
#### `patch_sequence`
Add new activities and messages to an existing sequence.
### State machine
#### `render_state_machine`
Render a UML-style state machine: states (with `initial` / `final` / `error` kinds) connected by transitions labeled `trigger [guard] / action`. Best for "what states does X go through?", "show me the lifecycle / error handling" questions.
#### `patch_state_machine`
Add new states and transitions to an existing state machine.
### ER diagram
#### `render_er_diagram`
Render a database / data-model ER diagram: tables with PK/FK badges and FK relationships wired field-to-field. Best for "show me the schema" questions.
### Code tour (high verbosity)
#### `render_code_tour`
Walk the cursor through a curated subset of real code-graph nodes (files / symbols) step-by-step with per-step rationale. Each step targets a path-anchored ref the host resolves against the workspace symbol index (`src/foo.ts`, `src/foo.ts:bar`, `src/foo.ts:42`). Use when verbosity is set to **high**.
## Configuring AI clients
Supported clients:
Per-call `--mcp-config` managed by the extension
Auto-managed `~/.codex/config.toml` block
# Quick Start
Source: https://docs.nogic.dev/quickstart
Get Nogic running in under 2 minutes
## Step 1: Install the extension
Install **Nogic** from the VS Code Marketplace:
1. Open VS Code
2. Open the Extensions sidebar (`Cmd+Shift+X` / `Ctrl+Shift+X`)
3. Search for **Nogic** (publisher: `Nogic`)
4. Click **Install**
Or install from the command line:
```bash theme={null}
code --install-extension Nogic.nogic
```
VSCodium and other Code OSS forks work too (Nogic supports VS Code engine `1.88.0+`).
## Step 2: Open the visualizer
Open any project folder, then either:
* Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and run **Nogic: Open Visualizer**, or
* Click the Nogic icon in the editor title bar
The first time, Nogic will offer to **Index Workspace**. Accept it. The extension scans your files, parses symbols (JS / TS / Python today), and stores everything locally under `~/.nogic/workspaces/`. Files in other languages appear in the tree without parsed symbols; the AI canvas (Step 5 below) still works on them.
Nogic also opens the visualizer automatically when you open a workspace. Disable that in Settings → Extensions → Nogic → `nogic.openOnStartup` if you prefer manual control.
## Step 3: Explore the graph
You're now looking at your codebase as a connected map.
* **Pan / zoom** with trackpad or scroll wheel
* **Search** with `Cmd+F` (or `Ctrl+F`) to jump to a file or symbol
* **Right-click** any node and choose **Inspect** to focus it with its connections
* **Right-click** files or folders in the Explorer and choose **Add to Nogic Board** to build a focused view
See the [Visualizer](/features/visualizer) page for the full feature tour.
## Step 4: Connect an AI client
Nogic ships a local MCP server that lets AI clients draw answers directly on the canvas via `Cmd+K`.
When you first open the visualizer, the **MCP Setup** overlay appears with:
* Whether **Claude Code** and **Codex** are installed and on your `PATH`
* The local MCP server URL (e.g. `http://127.0.0.1:54123/mcp`)
* Toggles to enable each CLI
Install whichever CLI you'd like to use, toggle it on, and dismiss the overlay. You can reopen it anytime via **Nogic: Show MCP Setup**.
Set up Claude Code (`Cmd+K` and external use)
Set up Codex (auto-managed config)
## Step 5: Ask a question on the canvas
With the visualizer focused, press `Cmd+K` (or `Ctrl+K`). The on-canvas **Director cursor** opens. Type something like:
> Walk me through how authentication works in this app.
Nogic streams your prompt to the active CLI, which calls the local MCP server. Within seconds the canvas reflows into a diagram with a step-by-step narrative: sequence, dataflow, state machine, ER, or a curated tour of real code, depending on the question.
See [Agent Canvas](/features/agent-canvas) for what the AI can render and how to drive it.
## Next steps
Boards, inspect mode, search, auto-sync
What the AI cursor can draw on the canvas
AI-driven diff map with risk and blast radius
The MCP server and the canvas tools it exposes
# Reference
Source: https://docs.nogic.dev/reference
Commands, keybindings, settings, and data layout
## Commands
All commands live under the `Nogic:` prefix in the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`).
| Command | What it does |
| ------------------------ | ---------------------------------------------------------------- |
| `Nogic: Open Visualizer` | Open (or focus) the visualizer panel |
| `Nogic: Open Diff Board` | Open the live current-diff board |
| `Nogic: Show MCP Setup` | Reopen the MCP setup overlay |
| `Nogic: Sign In` | Sign in to Nogic |
| `Nogic: Sign Out` | Sign out of Nogic |
| `Add to Nogic Board` | (Explorer context menu) Add a file or folder to the active board |
## Keybindings
| Action | Mac | Win/Linux | Scope |
| ----------------- | ------- | --------- | ---------------- |
| Focus search | `Cmd+F` | `Ctrl+F` | Visualizer panel |
| Open AI cursor | `Cmd+K` | `Ctrl+K` | Visualizer panel |
| Open file browser | `Cmd+I` | `Ctrl+I` | Visualizer panel |
The visualizer-only scope keeps these bindings from clashing with VS Code's editor-level shortcuts elsewhere.
## Settings
Configure under Settings → Extensions → **Nogic**, or in `settings.json`:
| Key | Type | Default | Description |
| -------------------------------- | ------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `nogic.openOnStartup` | `boolean` | `true` | Auto-open the visualizer when a workspace opens |
| `nogic.telemetry.enabled` | `boolean` | `true` | Anonymous usage telemetry. Respects VS Code's global telemetry setting |
| `nogic.walkthrough.preferredCli` | `"auto" \| "claude" \| "codex"` | `"auto"` | Which CLI handles `Cmd+K`. `auto` probes both at startup |
| `nogic.walkthrough.enabledClis` | `string[]` | `["claude", "codex"]` | Which CLIs are allowed to handle `Cmd+K`. Toggle via the MCP Setup overlay |
| `nogic.diffAnalyze.modelTier` | `"cheap" \| "medium"` | `"medium"` | Model tier for Diff Analyze canvas authoring. See [Diff Analyze tuning](#diff-analyze-tuning) below |
| `nogic.diffAnalyze.concurrency` | `number` (1-16) | `8` | How many canvas authoring runs in flight simultaneously. See [Diff Analyze tuning](#diff-analyze-tuning) below |
| `nogic.walkthrough.agentBaseUrl` | `string` | `https://api.nogic.dev` | *Deprecated.* Legacy backend URL — Cmd+K and canvas authoring now run locally via your CLI |
| `nogic.walkthrough.apiKey` | `string` | `""` | *Deprecated.* Legacy backend key — see above |
### Diff Analyze tuning
Two knobs control the cost/quality and cost/speed trade-offs for Diff Analyze canvas authoring. **Most users never need to change these** — the defaults work well for Claude Pro/Max and Codex Plus/Pro subscribers.
#### `nogic.diffAnalyze.modelTier`
Controls which model tier authors the per-group canvases.
| Value | Models used | Trade-off |
| -------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `medium` *(default)* | Sonnet (Claude Code) / codex-grade (Codex) | Reliable connection authoring, accurate hunk anchoring, supports Before/After diagrams. Higher cost per group. |
| `cheap` | Haiku (Claude Code) / mini (Codex) | \~3-5× cheaper, \~30% faster. Sparser hunks; multi-file diagrams may miss connections. |
**Switch to `cheap` when:** you're on a pay-as-you-go API tier and want to control cost; your typical diffs are small/single-file; you're iterating quickly and quality variance is acceptable.
**Stay on `medium` when:** you're on Claude Pro/Max or Codex Plus/Pro (flat-rate plans — no per-call cost); your diffs span multiple files; you're using Diff Analyze for actual code review, not just exploration.
Cmd+K is unaffected by this setting. Cmd+K always uses cheap (foreground, single-turn — Haiku is plenty for that use case).
#### `nogic.diffAnalyze.concurrency`
How many canvas authoring runs the parallel dispatcher allows in flight at once.
| Value | When to pick |
| --------------- | ------------------------------------------------------------------------------ |
| `1-2` | Anthropic API tier 1 (default new accounts) or aggressive rate limits |
| `4` | Anthropic API tier 1 with light usage |
| `8` *(default)* | Claude Pro/Max, Codex Plus/Pro, Anthropic API tier 2+ |
| `12-16` | Anthropic API tier 3+ — benchmark first to confirm your tier handles the burst |
Higher values finish a 30-group diff faster (\~15s vs \~60s typical), but multiply peak in-flight calls. If your AI provider rate-limits, you'll see silent failures and need to use **Refresh All Stale** in the Diff Analyze toolbar to recover. The setting takes effect immediately on the next canvas authoring run — no extension restart needed.
## Local data layout
```
~/.nogic/
workspaces/
/
nogic.db # SQLite index for this workspace
saved_walkthroughs/ # AI canvas walkthroughs saved per workspace
~/.codex/
config.toml # Auto-managed [mcp_servers.nogic] block (Codex only)
config.toml.nogic.bak # Backup of original codex config (created on first write)
```
Nothing here is sent off your machine. Delete `~/.nogic` to wipe all extension data.
## Privacy & telemetry
Nogic collects anonymous usage metrics (feature use counts, performance timings) to help prioritize what to work on. It never collects:
* Code, file contents, or paths
* Symbol names
* Prompts you type into the AI cursor
* AI responses
Disable telemetry with `nogic.telemetry.enabled = false`, or globally by setting VS Code's `telemetry.telemetryLevel = "off"`. See [nogic.dev/telemetry](https://nogic.dev/telemetry) for the full list of events.
## Language support
Nogic has two surfaces and they support different languages.
### Code graph (parsed)
These features depend on Nogic's symbol index:
* Visualizer (the connected graph view, boards, inspect mode)
* Diff Analyze (smart ordering, blast radius, change groups)
* The MCP `render_code_tour` tool
Supported languages:
* **JavaScript / TypeScript** (including JSX/TSX): full call graph and import detection, including `tsconfig` / `jsconfig` path aliases, TS ESM (`.js` → `.ts`), and JSON/YAML config imports
* **Python**: class / function / method extraction, imports, basic call resolution
Files in other languages appear in the file tree but don't contribute symbols or edges.
### AI canvas (any language)
`Cmd+K` and every MCP canvas tool except `render_code_tour` work on **any language**. The AI client reads source with its own native `Read` / `Glob` / `Grep`, so the `render`, `patch`, `render_dataflow`, `render_sequence`, `render_state_machine`, and `render_er_diagram` tools don't depend on the symbol index.
More parsed languages are planned. AI canvas language coverage is automatic: anything the AI client can read, it can diagram.
## Engine compatibility
* VS Code `1.88.0+`
* VSCodium and other Code OSS forks at the same engine version
The extension uses the VS Code MCP provider API (`vscode.lm.registerMcpServerDefinitionProvider`) when available (`1.102+`). On older VS Code versions, the local MCP server still runs and external CLIs can still connect; only the auto-registration into VS Code's built-in AI ecosystem is skipped.
## Support
* Discord: [discord.gg/25bdAnuB4Y](https://discord.gg/25bdAnuB4Y)
* Email: [support@nogic.dev](mailto:support@nogic.dev)
* Website: [nogic.dev](https://nogic.dev)