Bodega Map

Two ways to open it:

1. Click the connected-nodes icon in the activity bar (the far-left vertical strip in Code mode, below the horizontal separator line).
2. Type /map in any panel input.

On the Dockview layout (default), the Map opens as a panel tab alongside your editor files. On the legacy layout engine, it opens as an editor tab - same mechanism as the Settings tab. Both layouts work identically from this point on.

If the button is missing, check Settings → UI → Show Codebase Map (ui.code_map_enabled). When it's off, /map shows a toast instead of opening the panel.

Re-clicking the button or typing /map again activates the existing surface rather than opening a duplicate.

Once a project is open, the graph loads automatically. Each card (node) represents a file. The cards show:

• Filename and top-level directory
• ↑N - exported symbol count
• ·N - internal symbol count
• Amber dot (top-right corner) - the cached explanation for this file is out of date because the file changed

The left accent bar encodes importance score: a more opaque bar means a more central file.

Edges between cards represent real import/require/script-src relationships (solid purple lines). When the graph is very sparse, structural fallback edges fill it in (dashed, lower opacity). Graphs with more than 150 visible nodes suppress structural edges to reduce visual noise.

Supported languages: TypeScript, JavaScript, Python, Go, Rust, Java. HTML, CSS, JSON, and Markdown files are also included.

Canvas controls:

• Pan: click and drag the background
• Zoom: scroll wheel or pinch
• Zoom controls: bottom-left corner buttons (zoom in / zoom out / fit all)
• Minimap: bottom-right - click or drag to jump to any area
• Select a node: single-click - dims non-neighbors and opens the detail drawer
• Open a file: double-click any node
• Deselect: click the canvas background

The graph is cached for 60 seconds server-side. Click the circular-arrow Refresh button (toolbar, far right) to force a rebuild after adding or deleting files.

Single-clicking a node opens a drawer that overlays the right edge of the canvas. It shows:

• Full relative file path
• Symbol count, exported count, internal count, external import count, importance score
• Symbol kinds as tag pills (e.g. function, class, interface)
• A clickable symbol list - each entry shows the name, kind, and line number
• The Explanation section (see below)
• An Open file button at the bottom

Clicking a symbol name opens the file in the editor and scrolls to that symbol's line. Clicking Open file opens the file at the top. Click X to close the drawer and deselect the node.

On Dockview, opening a file surfaces the editor panel forward automatically so you see the file rather than staying on the Map.

Each file node can have a 2–4 sentence plain-English explanation of what it does and its role in the project.

1. Single-click a node to open the detail drawer.
2. Scroll to the Explanation section.
3. Click Explain this module.
4. The model reads the file content (up to 8,000 characters) plus its exported symbols and import paths, then writes the summary.
5. Once generated, click Regenerate to refresh it.

Explanations are cached in SQLite by content hash. An unchanged file returns its cached explanation instantly - no model call. After the file changes, a yellow "This page is out of date" badge appears above the button, and an amber dot shows on the canvas node.

Air-gap restriction: when air-gap mode is on, generation only works with a locally-hosted provider (localhost/127.0.0.1). Cloud providers return a 403 under air-gap.

Generate Map runs "Explain this module" for every currently visible file - 4 files at a time.

1. (Optional) Use the filter bar and Hide tests to scope to the files you care about.
2. Click Generate Map in the toolbar.
3. Watch the Generating N/M counter. Click Cancel to stop at any point.

Already-cached files return instantly (no model call). A re-run only regenerates files whose content changed. After the run completes, the staleness set refreshes and amber dots clear for newly-generated files.

Generate Map is currently frontend-orchestrated - up to 4 concurrent requests fire from the browser.

The Project overview section sits above Ask the Map at the bottom of the panel. It produces a one-page Markdown architecture summary (~250–400 words) that rolls up the per-file explanations already cached - no file re-scan.

The output includes: a short project description, a Key areas section grouping modules by responsibility, and a Where to start section pointing to the 2–3 most central files.

1. Click Project overview at the bottom of the panel to expand it.
2. On first open it auto-generates (or serves the cached version).
3. Click Regenerate inside the section to force a refresh.

If no per-file summaries exist yet, it shows: "No module summaries to roll up yet. Use Generate Map first."

The overview is cached and regenerates automatically when the underlying module summaries change. The same model picker and air-gap rules apply. It rolls up at most 80 per-file summaries in a single prompt.

Ask the Map answers free-form questions about your project using semantic search over the codebase embedding index.

1. Click Ask the Map at the very bottom of the panel.
2. Type a question (e.g. "where is auth handled?", "how does the streaming loop work?").
3. Press Enter or click Ask.
4. The answer appears with clickable source chips below it - click any chip to open that file in the editor.

Ask the Map requires two models: the chat model (Map toolbar picker or your active default) generates the answer; a separate embeddings model powers retrieval. See the Codebase Embeddings settings section below for how to configure that.

If the embedding index hasn't been built yet, the first question triggers a background index build and returns a message telling you to ask again in a few seconds. If the embeddings provider is set to Off, the response tells you where to turn it on.

Questions are capped at 2,000 characters. Air-gap mode requires a localhost provider - same rule as Explain.

Bodega tracks which cached explanations are out of date without requiring any manual check. On each Map panel mount and after each Generate Map run, it compares the stored content hash of each cached file against the file's current content on disk.

Stale files get:

• An amber dot in the top-right corner of their canvas node (tooltip: "Map page is out of date - this file changed since its page was generated")
• A yellow banner in the node detail drawer when that node is selected

To fix staleness: click the node and click Explain this module (or Regenerate), or run Generate Map to refresh all stale files at once.

The staleness check is read-only and local - it hashes files on disk, nothing leaves the machine, and there's no air-gap gate on this endpoint. Deleted files read as stale (their cached explanation describes code that no longer exists).

Ask the Map requires a separate embedding model - distinct from your chat model. Claude, GPT, and Gemini don't do embeddings; Anthropic has no embeddings API. Even if you use a cloud chat provider, you still need an embedding model for retrieval.

Settings → Models → Codebase Embeddings

Ollama setup: ensure Ollama is running. The default model (qwen3-embedding:4b) pulls automatically. The Model field is free-text - type any model you've already pulled.

Auto-index: off by default. When on, Bodega rebuilds the embedding index 60 seconds after a project opens.

Changing models: if you switch to a different embedding model after an index already exists, a banner appears: "Existing index was built with X, rebuild required." Search will fail until you rebuild. Use the Rebuild button in the Context Inspector (Code mode, next to the Repo Map section).

Settings keys: embeddings.provider, embeddings.model, embeddings.base_url, embeddings.api_key, embeddings.auto_index

Instead of running llama-server --embedding yourself, Bodega can own and manage that process.

1. Go to Settings → Models → Codebase Embeddings.
2. Select llama.cpp as the provider.
3. Check Let Bodega manage the embedding server.
4. Pick an installed GGUF from the dropdown, or type an absolute path manually.
5. Set the port if 8081 conflicts with anything else on your machine.

The server starts lazily - on the first index build, not immediately. It runs on loopback port 8081 (configurable) and is completely separate from the chat llama-server (which uses port 8080).

The GGUF dropdown shows models you've already downloaded in Models → llama.cpp → Discover. External GGUFs not downloaded through Bodega must be entered as a manual absolute path.

Requires the llama.cpp binary to be installed (Settings → Models → llama.cpp → install).

Settings keys: embeddings.llamacpp_managed, embeddings.llamacpp_model_path, embeddings.llamacpp_port

The query_map tool exposes Ask the Map to Bodega's agentic loop. When the agent is working in an unfamiliar part of your codebase, it can call query_map with a natural-language question before editing rather than grepping through files blindly.

It returns { answer, sources, model } - the same grounded answer and source files the UI shows. Source file paths appear as a tool_call card in the agent panel when the tool runs.

You can prompt the agent to use it explicitly: "Before editing the auth flow, find out where authentication is handled in this project."

The tool requires the same codebase embedding index as the Ask the Map UI. If the project isn't indexed yet, the answer says so - it never throws. If no project is open, it returns: "No project is open, so the codebase Map cannot be queried."

Timeout: 65 seconds. Honors air-gap mode. Read-only - it never writes to the index.