Docs Using Blacksite

Using the Codebase Map

The Codebase Map is a rendered star-field of your repository. Files are stars, relationships are arcs, and folders form coloured territories. A separate Services lens rolls files up into deployable units and the typed routes between them.

You do not need a graph-theory background to use it. Start by searching for a file you know, selecting it, and choosing Focus this neighborhood.

It is genuinely useful to look at. But the reason it exists is that the agent queries the same graph you are looking at. When it needs to know what a change reaches, it does not grep for import statements and guess — it asks the index.

For the architecture behind it, read Codebase Map. This page is about using it.

Opening it#

• Blacksite: Open Codebase Map — in the sidebar container.
• Blacksite: Open Codebase Map in Editor — as a full editor tab, which is where you want it for real exploration.
• Blacksite: Rebuild Codebase Map Index — force a full reindex if something looks stale.

The index builds in the background on first open and updates as you work.

Reading the map#

Stars are files. Size reflects significance—a file everything imports is bigger than a leaf. Colour identifies the file’s folder territory, so nearby areas stay recognizable across sessions. A small role mark distinguishes tests, configuration, docs, styles, data, types, assets, and entry points without turning star colour into a second legend.

Arcs are relationships, and they come from several layers:

• Imports — resolved per language, not pattern-matched. TypeScript path aliases from tsconfig.json, Go module paths, Java and C# namespaces, Python packages and re-exports, PHP autoload rules.
• Service relationships — one service calling another’s HTTP API, publishing an event another consumes, or writing a table another reads. Detected across roughly ten frameworks.
• Symbol relationships — calls, references, and inheritance, from your installed language servers. Off by default; see performance below.
• Notes — durable annotations, including relationships the indexers cannot see.

Territories are neighborhoods. Distinct codebases within a workspace get their own region, subdivided by folder. Controlled by blacksite.graph.neighborhoods (auto / on / off).

Stars sit at different depths. Near stars are crisp and full-size; far ones fade toward the background, shrink slightly, draw behind their neighbours, and drift a little more slowly as you pan. What distance means is yours to choose, under Layers → Depth:

The default is folder nesting rather than connectedness on purpose: star size already encodes how connected a file is, so spending depth on the same signal would say one thing twice. Slide Intensity to Flat to switch the whole cue off.

The Services lens is a different view of the same index. It shows one diamond per deployable service and bundles verified API, event, shared-data, and configuration relationships between them. Switch back to Files when you need individual source files.

On the precision of service edges#

A naive service matcher pairs any route string with any similar-looking URL and produces a hairball. Blacksite requires the client side of a call to be verified before drawing the edge. The consequence is that a line on the map means a call that plausibly exists, rather than two strings that rhyme — and that some real relationships are missing rather than invented. That trade is deliberate. If a relationship matters and the indexer cannot see it, attach a note; notes become first-class edges.

Navigating#

Selecting a star opens the inspector: its path, role, connection count, change heat, and any notes attached to it. From there you can focus its neighborhood — isolating that file and everything it touches, which is usually the view you actually wanted.

Large and multi-codebase workspaces#

A workspace with tens of thousands of files, or several codebases across several folders, is not readable as one star field. For those the map opens on the Systems overview: one node per codebase, sized by how many files it holds, joined by the relationships between them — imports, API routes, events, shared data, dependencies declared in manifests, and hidden coupling (dashed: two codebases keep changing in the same commits, but nothing in the code connects them). Smaller workspaces open on files, as before; blacksite.graph.landingView sets this explicitly.

From there you work inward:

Inside a scope the map draws up to the focus budget (Display & analysis → Advanced, 2,500 by default). When there is more than that, areas fold into single stars; the area you select and wherever the agent is working stay unfolded. The folded star says how many files it stands for — the true count, including files not drawn yet — and stepping into it draws them all.

Star colors follow the hierarchy: every folder of a codebase shares that codebase’s hue family, so at file level you can still tell which codebase a star belongs to.

The outline#

The Outline panel on the left lists every folder, codebase, project, and area with its file count. Each row also shows open tickets, map notes, a live dot while the agent is working there, and a thin bar for recent change heat. Click a row to scope the map to it; hover to preview it on the canvas. When there are findings, Dependency findings lists cross-project imports no manifest declares and declared dependencies nothing imports.

The inspector#

Selecting anything opens the inspector at the bottom left, with tabs:

• Overview — what it is: role, size, links, change history, and for a group its languages and true file count.
• Relations — grouped by kind and by counterpart; links into another codebase are marked.
• Work — open tickets covering it, and File a ticket here.
• Activity — Execution Runs that touched it, with Replay on map and Open run.
• Notes — map notes on it or inside it; Open in timeline opens the Notes timeline filtered to it.
• Refs — documents you attached to conversations that name it, by path, by an unambiguous file name, or by an API route it serves.

Live agent traces#

When the agent works, the map shows it. Files it reads pulse; files it edits flare; the working directory of a shell command lights up.

Traces fade over blacksite.graph.traceFadeSeconds (default 45). Shell activity can be turned off with blacksite.graph.traceShellEvents.

This is the single most useful thing about having the map open while the agent runs. You can see at a glance whether it is working where you expected — and when it wanders into an area you did not anticipate, that is usually worth interrupting to ask about.

Ticket heat#

Turn on the Ticket heat layer to see where open work is concentrated. Tickets attach to files or folder areas; the map resolves that territory against the current index and weights it by priority. The busiest files glow cool cyan, deliberately distinct from the warm git-change heat layer.

Select a glowing file to inspect it, then open the Tickets view or Board for the full work item. See Tickets & the Board for how territory is recorded.

The queries the agent can run#

The map is the agent’s structural sense. These are the tools it has against it, and knowing them tells you what to ask for:

map_overview — orient in the whole workspace. The codebases across every open folder and what each depends on, hidden coupling between them, dependency findings (imports no manifest declares, declared dependencies nothing imports), detected projects and project-to-project references, major code areas, dependency hubs, cross-service flows, structural findings (cross-project cycles, orphan files, single-access pockets), index coverage, and recent notes. Every section is ranked and capped, so it is the top of a list rather than the whole list.

map_find — enumerate files with filters and ranking, optionally within one codebase. “Which files are in src/graph”, “the most-connected files under this area”, “Python files with no dependents”, “what has churned most recently here”. Each result carries its area, language, dependent/dependency counts, size, and recent-commit count.

map_relationships — one hop out from a file: what it imports, what imports it, cross-service relationships with evidence, the files it keeps changing together with (changedWith), and attached notes.

map_impact — the transitive blast radius, N hops out, with the concrete edge chain connecting each file back to the seed. Grouped by depth and by area, so you can see immediately whether a change is contained or reaches across the system. This is the one to ask for before touching a shared contract.

map_path — how two files are actually connected: the shortest chains between them, one entry per hop with the edge kind. For “how does this webview message reach the store” — you know both ends and need the middle.

map_note_* — add, list, update, and remove durable notes.

Asking for these directly#

You do not have to name the tools, but naming the question helps:

• “What’s the blast radius if I change the session store?” → map_impact
• “How is the chat input connected to the provider client?” → map_path
• “What are the dependency hubs in this repo?” → map_overview
• “Which files under src/lsp have no dependents?” → map_find

Notes: the map’s memory#

Notes are how knowledge survives the end of a session.

The agent attaches them as it learns things — the durable, non-obvious why. Not “this file exports a component” (visible from the code) but “this retry backoff must stay under the gateway TTL or requests double-fire”. Each note has a category: architecture, gotcha, todo, risk, or question.

Notes can attach to a file or to a relation between two files. Relation notes are how you record an edge the indexers cannot see — an event flow, an IPC route, a config-to-consumer link. They render on the map as labelled connections and are traversable as a layer in map_impact and map_path.

Before adding, the agent lists existing notes and updates a related one rather than creating a near-duplicate, keeping a bounded revision history.

Browse them all with Blacksite: Open Map Notes Timeline, which shows them chronologically alongside git history and diffs.

You can and should write notes yourself. A note you leave is context every future session inherits.

Performance#

Force-directed layout — treating edges as springs and nodes as mutually repelling particles — produces genuinely good results, because related things cluster naturally. It is also roughly O(n²) per tick: beautiful at 2,000 nodes, unusable at 60,000. Above a threshold of 6,000 nodes Blacksite switches to a linear-time phyllotaxis-style packing instead.

You control the caps with blacksite.graph.performanceProfile:

The advanced caps — maxIndexedFiles, maxRenderedStars, maxRelationshipEdges — each default to 0, meaning “use the profile”. Set them only when you need something the profiles do not give you.

How indexing stays out of the way#

Reading, extracting, resolving, and laying out a large workspace happens in a background worker, so chat and the agent stay responsive while the map rebuilds. What each file contributes is cached in .blacksite/graph-facts.json, so reopening a workspace re-reads only the files that changed; the service-relationship pass is cached the same way. While the map is open, an edit sends only what changed rather than the whole graph.

Imports between packages resolve through the workspace itself: import "@acme/ui" reaches that package’s source through its package.json (exports, main, types, or src/index), a Rust use sibling_crate::… reaches the sibling crate, and a Python project’s declared source root (src/ layouts) is searched for absolute imports — across workspace folders too.

What the map does not index#

By default the map follows your .gitignore (blacksite.graph.respectGitignore): it indexes the files git tracks plus untracked files that are not ignored. Generated clients, vendored trees, and build output your repository ignores stay off the map. When this applies, the command panel says Following .gitignore with an Include ignored button. Folders that are not git repositories are scanned as before.

Directories whose name begins with a dot hold tooling state, not authored source, and are skipped by default (blacksite.graph.excludeDotDirectories). This is usually the single biggest thing you can do for a map’s signal: on this extension’s own repository, .vscode-test — a downloaded VS Code build kept as a test fixture — was 560 of 1,256 indexed files. Every one of those was read, import-scanned, laid out by the force solver, and drawn, while also skewing cul-de-sac detection, cycle detection, and the capacity profile that gets auto-selected from your true file count.

When the rule hides something, the map says so above the search box, with a Show button. To keep a specific directory, add it to blacksite.graph.dotDirectoryAllowlist — [".github"] is the common one. The leading dot is optional and matching is by directory name at any depth.

Dot-files are always kept: .env, .eslintrc.json, and nginx-style configs are authored configuration, and the service lens reads them as evidence. And .git, .blacksite, .next, and .venv are never indexed regardless of this setting — turning it off will not re-admit them.

Background symbol indexing#

blacksite.graph.backgroundSymbols (off by default) indexes call, reference, and inheritance relationships across the whole codebase using your installed language servers. It runs on an idle budget and pauses while you edit, but it is genuinely more expensive than import scanning.

Turn it on when symbol-level precision is worth it. Leave it off otherwise — and note that while it is off, map_relationships reports symbolRelationsUnavailable: true rather than silently returning an empty set, so neither you nor the agent mistakes “not analyzed” for “none”.

Related#

• Codebase Map architecture — the indexing, layout, and rendering design
• Tool Reference — the full map tool surface
• Settings & Commands — every blacksite.graph.* setting