Docs Reference
Settings & Commands
Browser & Research has a dedicated panel under Agent & delegation. Its settings are
blacksite.research.allowedDomains, deniedDomains, unknownDomainPolicy, searchProvider
(none, hosted for the model provider’s built-in search, or brave), searchScope (any or
approved), and the human-default blacksite.browser.inputApprovalMode preference. File edits cannot
widen grants or activate delegation; confirm policy and session scope through the panel.
See Browser & Research for effective-list precedence and limitations.
Everything Blacksite exposes, in one place. Settings live under the blacksite.* namespace; open
them with Preferences: Open Settings and search for blacksite, or edit settings.json
directly.
Several settings are also reachable from the Settings panel inside the Blacksite sidebar, which writes to the same values.
The defaults are intended to be usable. If you are looking for a button or command, jump to Commands; the settings tables are technical reference for the cases where you deliberately want different behavior.
Lifecycle scripts are configured on the Hooks page (Blacksite: Manage Hooks), which
writes the user-only blacksite.hooks.commands setting (default: no hooks). See
Lifecycle hooks for the events, JSON protocol,
blocking behavior, and examples. If a hook seems to do nothing, press its test button on the
Hooks page, or run Blacksite: Check Lifecycle Hooks.
Finding your way around#
The view switcher at the top of every Blacksite panel lists all workspace views and recent places. Its Back button returns to the previous view. Ticket selections and plan phase expansion survive switching views. Linked tickets, plans, and execution evidence open the referenced item directly.
Use Text → Comfortable for larger text and controls, or Compact for the original density.
This is the user-level blacksite.interface.density setting and applies to all Blacksite panels.
In Settings, Search settings searches control names and descriptions across all sections. Results show their workflow and section; choosing one opens, highlights, and focuses its control. Try budget, compression, or domains. Controls that depend on a feature or provider explain when they are available. Settings remembers your last section. Longer explanations are under Details, and status chips are under Current configuration.
Provider and model#
| Setting | Default | What it does |
|---|---|---|
blacksite.provider |
anthropic |
The active provider (anthropic, openrouter, openai, bedrock), mirrored from the sidebar Settings. A user-level value seeds a new install |
blacksite.chatgpt.codexPath |
(empty) | Absolute path to the Codex executable for ChatGPT subscription sign-in. Blank uses the Codex VS Code extension or codex on PATH. Reload the window after changing |
blacksite.chatgpt.reasoningSummary |
detailed |
How much of the model’s reasoning ChatGPT summarizes in the chat: auto, concise, detailed or none. ChatGPT sends no reasoning unless asked, and some models return none even when asked. Applies to the next request |
blacksite.chatgpt.verbosity |
medium |
How long ChatGPT’s answers run: low, medium, high, or default to leave the model’s own setting (low for every ChatGPT model). Applies to the next turn |
blacksite.chatgpt.reuseConversation |
true |
Keep one ChatGPT conversation open across the agent’s steps instead of starting a new one for every model call. Blacksite starts a fresh one whenever its transcript and ChatGPT’s would disagree |
blacksite.chatgpt.extendedContext |
false |
Ask ChatGPT for the model’s largest context window (872K tokens on GPT-6 and GPT-5.6 models) instead of the 272K default. Long conversations then send more tokens with each request, which uses more of your allowance |
blacksite.bedrockApi |
converse |
Bedrock API path, mirrored from the sidebar Settings. converse for live model listing and dated inference profiles; mantle for the Anthropic-native Messages endpoint required by the newest Claude models |
blacksite.model |
"" |
The active model, mirrored from the sidebar for reference. Change it in the sidebar or with /model |
blacksite.workspaceRoot |
"" |
Workspace root for the local runtime. Empty uses the first workspace folder |
API keys are not settings. They live in SecretStorage — see
Providers, Keys & Models.
Permissions#
These control what the agent may execute and read. Most are scoped to the resource, so you can set them per workspace.
| Setting | Default | What it does |
|---|---|---|
blacksite.permissions.allowedCommands |
[] |
Extra terminal binaries the agent may run, added to the built-in allowlist. Compared by command name, case-insensitive |
blacksite.permissions.deniedCommands |
[] |
Binaries the agent may never run. Overrides both the allowlist and auto-approve |
blacksite.permissions.autoApprove |
[] |
Binaries whose network/destructive operations run without a prompt. Populated by choosing “Always allow” on an approval. Workspace entries apply only once confirmed on this machine |
blacksite.permissions.allowEvalFlags |
false |
⚠️ Runs inline code (node -e, python -c, ruby -e, …) without asking. By default it always shows an approval prompt with the code, even for programs you always allow. Also permits arguments that make a program launch another one (find -exec, node -r, …), which are otherwise refused. User settings only |
blacksite.permissions.readToolchains |
true |
Lets the agent read installed toolchains outside the workspace (PATH directories and their installs’ library folders) without asking. Anything else outside the workspace always asks |
blacksite.permissions.readableRoots |
[] |
Extra folders outside the workspace the agent may read without asking. User settings only |
Deny beats everything. If a binary is in deniedCommands, no allowlist entry and no auto-approve
decision will let it run.
allowEvalFlags deserves its warning. Enabling it lets the agent execute arbitrary code passed
directly on a command line — which routes around the tool-level gating entirely, because the shell
does not know the difference between node build.js and node -e "<anything>". Leave it off unless
you have a specific reason and understand what you are trading.
Full discussion in Approvals & Safety.
Codebase Map#
| Setting | Default | Range | What it does |
|---|---|---|---|
blacksite.graph.performanceProfile |
balanced |
safe, balanced, large, extreme, custom |
Capacity profile for indexing and rendering |
blacksite.graph.maxIndexedFiles |
0 |
0–250,000 | Advanced: max files scanned. 0 uses the profile |
blacksite.graph.maxRenderedStars |
0 |
0–100,000 | Advanced: max stars rendered. 0 uses the profile |
blacksite.graph.maxRelationshipEdges |
0 |
0–150,000 | Advanced: max relationship edges sent to the map. 0 uses the profile |
blacksite.graph.maxNodes |
4000 |
100–20,000 | Legacy cap. Prefer the profile and advanced caps |
blacksite.graph.neighborhoods |
auto |
auto, on, off |
Whether distinct codebases get their own territories |
blacksite.graph.backgroundSymbols |
false |
Background-index call/reference/inheritance relationships via language servers. Higher cost; runs on an idle budget and pauses while you edit | |
blacksite.graph.excludeDotDirectories |
true |
Skip directories whose name begins with a dot (.vscode-test, .pytest_cache, .gradle, …). Dot-files like .env are always kept. .git, .blacksite, .next, and .venv are never indexed either way |
|
blacksite.graph.dotDirectoryAllowlist |
[] |
Dot-directories to index anyway, e.g. [".github"]. Matched by directory name at any depth; the leading dot is optional |
|
blacksite.graph.respectGitignore |
true |
Build the map from the files git tracks plus untracked files that are not ignored, so generated, vendored, and build-output trees your .gitignore excludes stay off the map. Tracked files are always included. Folders that are not git repositories are scanned as before |
|
blacksite.graph.landingView |
auto |
auto, systems, files |
What the map opens on. auto opens large or multi-codebase workspaces on the Systems overview (one node per codebase) and everything else on individual files |
blacksite.graph.traceFadeSeconds |
45 |
2–3600 | How long agent activity traces take to fade |
blacksite.graph.traceShellEvents |
true |
Show shell/terminal activity as working-directory pulses |
The three advanced caps default to 0 meaning “use the profile”. Set them only when a profile does
not give you what you need.
Data workbench#
| Setting | Default | What it does |
|---|---|---|
blacksite.data.previewPageSize |
50 |
Rows per page in the table preview |
blacksite.data.maxQueryRows |
500 |
Max rows returned by a read query |
blacksite.data.enableAssistant |
true |
Enable the natural-language database assistant |
blacksite.data.backendMode |
exact_local |
Vector backend: exact_local (SQLite, zero dependencies) or pgvector_container (local Postgres + pgvector sidecar) |
Browser#
| Setting | Default | What it does |
|---|---|---|
blacksite.browserHeadless |
false |
Run the agent’s browser without a visible window |
blacksite.browserExecutablePath |
empty | Full path to a Chromium-based browser (Chrome, Edge, Chromium, Brave). Empty detects one automatically |
Headed by default, so you can watch what the agent does. UI preview renders always run headless in a separate browser process, so checking a preview never opens a window or takes focus.
Browser tools, preview rendering and Execution Runs drive an installed Chromium-family browser — none
is bundled. Detection covers the standard and per-user install locations: Program Files (on any
drive) and %LOCALAPPDATA% on Windows, /Applications and ~/Applications on macOS. Set
blacksite.browserExecutablePath only if your browser lives somewhere else. It is a machine setting,
so a workspace cannot point it at a different program.
Execution Runs#
| Setting | Default | What it does |
|---|---|---|
blacksite.runs.temporaryRetentionDays |
7 |
Age limit for unpinned exploratory runs |
blacksite.runs.standardRetentionDays |
30 |
Age limit for unpinned standard runs |
blacksite.runs.maxRuns |
500 |
Maximum unpinned run count per workspace |
blacksite.runs.video.enabled |
false |
Allow the agent to explicitly record local browser video evidence. Recordings never start implicitly |
blacksite.runs.video.maxDiskMb |
512 |
Workspace disk budget for unpreserved browser recordings. Extracted keyframes don’t count against it |
blacksite.runs.video.degradeAfterDays |
1 |
Days before an unpreserved recording is reduced in frame rate and resolution, when ffmpeg is available |
blacksite.runs.video.deleteAfterDays |
3 |
Days before an unpreserved recording is deleted. Extracted and user-flagged keyframes remain |
blacksite.runs.video.keyframeIntervalMs |
500 |
Interval between retained adjacent keyframes sampled while browser video is recording |
Pinned baselines, active runs, and evidence referenced by active plans or open tickets are protected from automatic cleanup.
Tickets#
| Setting | Default | What it does |
|---|---|---|
blacksite.tickets.idPrefix |
BLK |
Prefix for ticket ids, e.g. BLK-12. Ticket ids leak into commit messages and branch names, so a project-specific prefix is often worth setting. Changing it does not renumber existing tickets |
blacksite.tickets.agentMayClose |
false |
Allow the agent to move tickets to Done itself. Off by default — the agent files, updates, comments, and moves work to Review, but closing stays your call |
Updates#
Blacksite updates from its own published releases, not the VS Code Marketplace. No credentials are involved — releases are public, and the updater never sends or asks for a token.
The check reads a static release manifest published with the site, falling back to the GitHub releases API only if that is unreachable. The manifest is one CDN request rather than a call against GitHub’s unauthenticated limit of 60 requests per hour per IP, which a single office behind one NAT can exhaust.
| Setting | Default | What it does |
|---|---|---|
blacksite.updates.checkOnStartup |
true |
Check for newer releases on startup, then every 3 hours while the window is open |
blacksite.updates.includePrerelease |
false |
Allow prerelease builds. Only the GitHub API lists prereleases, so this checks it first and falls back to the manifest if it is unreachable |
blacksite.updates.manifestUrl |
https://rooftopdude.github.io/blacksite-vscode/latest.json |
Release manifest checked first |
blacksite.updates.repository |
"" |
Owner/repo used as the fallback source. Blank uses the repository declared in the package |
Every check, automatic or manual, writes one line to the Blacksite Updates output channel: which channel and source it used, what it found, and why it did or did not offer an update. An automatic check that fails is retried after 30 minutes rather than at the next three-hour check.
MCP#
| Setting | Default | What it does |
|---|---|---|
blacksite.mcpServers |
[] |
MCP servers available in every project. Managed via Blacksite: Manage MCP Servers |
Each entry has id, name, transport (stdio or http), command or url, and enabled.
Optionally: args and cwd for stdio servers, env (as { "NAME": "value" }, or
[{ name, value, secret }] to keep a value in SecretStorage), headers for HTTP ones, auth
(mode of none/oauth/bearer/header, plus headerName, scopes, clientId,
redirectUri), transportHint to pin a protocol revision instead of probing for it, and
autoApproveReadOnly to run the server’s read-only tools without asking. ${env:NAME},
${NAME}, ${workspaceFolder} and ${userHome} are expanded in commands, arguments and values,
so a server definition copied from another client’s config usually works as it is.
Servers added for one project only are kept with that workspace rather than in this setting.
The setting is application-scoped on purpose: a repository’s .vscode/settings.json cannot
register a server, because that would let a cloned repo nominate a process for the extension to
launch.
Credentials never appear here. Tokens, OAuth grants, and secret environment values live in VS Code SecretStorage, and per-tool permissions live in extension state — so this setting stays safe to sync. Editing by hand works, but the command is easier and validates as it goes.
Integrations#
Trusted destinations for the built-in GitLab, Jira, Confluence, and Salesforce tools. All are application-scoped, so a workspace cannot silently point them somewhere else, and the credential itself always lives in SecretStorage — these settings only name where it is allowed to go.
| Setting | Default | What it does |
|---|---|---|
blacksite.integrations.gitlabHost |
https://gitlab.com |
Trusted HTTPS origin that may receive the stored GitLab token |
blacksite.integrations.jiraHost |
"" |
Trusted HTTPS Jira origin, e.g. https://example.atlassian.net. Required before Jira tools are exposed to the agent |
blacksite.integrations.confluenceHost |
"" |
Trusted HTTPS Confluence origin. Required before Confluence tools are exposed to the agent |
blacksite.integrations.salesforceInstanceUrl |
"" |
Trusted HTTPS Salesforce instance origin. Required before Salesforce tools are exposed to the agent |
Plan continuation and plan runs#
| Setting | Default | What it does |
|---|---|---|
blacksite.planContinuation.enabled |
false |
Automatically continue an approved plan when a turn ends without finishing it. A separate agent, holding your original prompts verbatim, decides whether to continue, escalate, or halt. Off by default — this spends model calls and agent turns with nobody watching. A plan run turns this on for itself, whatever the setting says |
blacksite.planContinuation.maxConsecutive |
5 |
How many times in a row the plan may be continued before stopping to check in. Resets whenever you send a message. During a plan run it counts only the automatic turns that finished no step, so a run making progress is not stopped |
blacksite.planRuns.retentionDays |
30 |
How long a finished plan run’s record (.blacksite/plan-runs/) and its restore points are kept |
blacksite.notifications.runEvents |
attention |
When Blacksite interrupts you outside the chat: attention (it needs you, failed, or finished), all, or off. Nothing is shown while you are looking at the chat, and a run’s own choice takes precedence |
Orchestration (experimental)#
Every setting here defaults to the previous behaviour. Setting one back to its default is the rollback: nothing it wrote is read again.
| Setting | Default | What it does |
|---|---|---|
blacksite.orchestration.workContracts |
off |
Work contracts for delegated lanes and loop tickets. observe gives each lane a contract (what it may change, its budget, its definition of done) and writes a receipt of what was actually observed — files changed, checks run — kept apart from what the lane said. Nothing about how work runs changes. enforce also asks before a lane writes outside its contract’s files (you, the reviewer, or Allow all can grant it) and lets the receipt decide a loop ticket’s outcome: a lane whose check failed goes back for another attempt instead of to review. Stored under .blacksite/orchestration/ |
blacksite.orchestration.workGraph |
false |
Builds a read-only work graph linking tickets, plan steps, code, runs and receipts, and gives the agent the work_graph tool for dependency, blocker, impact and critical-path questions. Derived from the existing stores, never written back |
blacksite.orchestration.signals |
off |
Typed signals about what the host observed: work completed, a check failing, scope growing, two pieces of work colliding, progress stalling, work becoming ready. observe journals them under .blacksite/orchestration/signals/ with what would have been done about each. act also lets a running loop re-check its queue the moment a blocker closes, and tells you when a loop that stopped on blocked tickets can continue. Signals never start or resume a loop, create work, close a ticket or change a limit; anything that needs judgment is flagged for you instead |
blacksite.orchestration.claims |
off |
Short-lived claims on the files a delegated lane is writing, checked at the moment of each write. observe records collisions: two lanes writing one file, or a lane overwriting a file another lane changed after it read it. enforce refuses those writes and names the other lane. Read-only work is never blocked, your own chat agent is warned rather than refused, and claims end with the lane. With claims on, a lane’s shell commands are also checked afterwards for files they changed outside the lane’s contract or inside another lane’s claims |
blacksite.orchestration.scheduler |
legacy |
How ticket loops choose what runs next. shadow chooses as before and records what the graph-aware scheduler would have chosen. graph runs tickets that unblock the most other work and sit on the critical path first, holds back tickets with a dependency cycle or a missing dependency, never starves a ticket, and records why each ticket ran. Needs blacksite.orchestration.workGraph; without it, behaves as legacy |
PAU (Beta)#
| Setting | Default | What it does |
|---|---|---|
blacksite.pau.enabled |
false |
Measure what’s consuming the agent’s context window each turn — token load, duplication, replay across turns, hog segments — using the PAU Profiler library, shown in the PAU panel. Read-only: it does not change what is sent to the model or how compaction behaves. Off by default while this gets real-world testing |
Preview#
| Setting | Default | What it does |
|---|---|---|
blacksite.preview.projectStylesheet |
[] |
Workspace-relative CSS files that question-card previews render against, so a preview uses the project’s own design tokens and component classes instead of hand-written CSS. Leave empty to auto-detect common build output or a conventional source entry such as src/index.css, src/globals.css, or app/globals.css |
Commands#
All available from the command palette under the Blacksite category.
Chat#
| Command | What it does |
|---|---|
| Open Chat Panel | Focus the chat view |
| Clear Chat | Start a fresh conversation |
| Stop Response | Stop the agent between tool calls |
| Open Plan Run | Show the chat and the current plan run; also what clicking the status bar item does |
| Pause Plan Run | Stop the run at the end of the tool call it is in |
| Resume Plan Run | Carry on a paused, interrupted or failed run from where it stopped |
| Stop Plan Run | End the run, after a confirmation. Work already done stays |
| Isolated Run Copies… | List this repository’s isolated run copies, to open one in a new window or remove it (its branch is kept) |
| Compact Conversation History | Summarize older history to reclaim context |
| Set API Key | Store a provider key in SecretStorage |
| Check Lifecycle Hooks | Report whether each configured hook can be found and started, and any mistake in the setting, without running anything |
| Show Execution Logs | Open the execution log for this workspace |
| Move Chat to the Right Side Bar | Move the Chat view to VS Code’s secondary side bar |
Code#
| Command | What it does |
|---|---|
| Explain Selection | Explain the selected code (Ctrl+Shift+E / Cmd+Shift+E) |
| Ask About This File | Start a request scoped to a file |
| Fix with Blacksite | Code action on a diagnostic — hands the agent the problem |
| Attach File To Chat | Attach a file to the current conversation |
| Add File To Base Context | Add a file reference to a Base Context topic |
| Clear Problems | Clear Blacksite-reported entries from the Problems panel |
Map#
| Command | What it does |
|---|---|
| Open Codebase Map | Open the map in the sidebar |
| Open Codebase Map in Editor | Open the map as a full editor tab |
| Rebuild Codebase Map Index | Force a full reindex |
| Open Map Notes Timeline | Browse durable notes with git history and diffs |
Execution Runs#
| Command | What it does |
|---|---|
| Open Execution Runs | Focus Run Explorer for retained timelines, evidence, and comparisons |
| Approve External Application for Read-Only Capture | Authorize an external app window for read-only browser evidence capture |
Tickets#
| Command | What it does |
|---|---|
| Open Tickets | Open the compact workspace queue |
| Open Ticket Board | Open the full-width board in an editor tab |
| File a Ticket | Record follow-up work, using the current file as territory when available |
| Propose Triage Tickets | Ask the agent to sweep for issues worth filing and stage them as triage tickets |
Ticket Loops#
| Command | What it does |
|---|---|
| Open Ticket Loops | Focus the Loops view |
| New Ticket Loop | Create a loop that works a set of tickets automatically |
Once a loop exists, its Start, Pause, Stop, Release Parked Ticket, and Delete actions are the icon buttons on that loop in the view — they operate on a specific loop, so they live inline rather than in the command palette.
PAU (Beta)#
| Command | What it does |
|---|---|
| Open PAU Panel (Beta) | Open the PAU panel. Requires blacksite.pau.enabled |
Data#
| Command | What it does |
|---|---|
| Open Data Workbench | Open the Data view |
| Refresh Data Catalog | Re-read the schema |
| Run Database Query | Run a query |
| Open Saved Query | Open a previously saved query |
Other#
| Command | What it does |
|---|---|
| Manage MCP Servers | Add, edit, enable, or disable MCP servers, choose their tools, and share them across projects |
| Import MCP Servers… | Add servers already set up in VS Code, Claude Code, Claude Desktop, Cursor or Windsurf |
| Use MCP Prompt… | Expand a prompt an MCP server offers and attach it to your next message |
| Attach MCP Resource… | Attach a document or record an MCP server publishes to your next message |
| Show MCP Log | Connections, server output and every MCP call |
| Manage Hooks | Add, edit, test and reorder lifecycle hooks, and see recent runs |
| Close Browser Window | Close the agent’s browser |
| Check For Extension Updates | Check GitHub for a newer release |
Keyboard and context menus#
Ctrl+Shift+E / Cmd+Shift+E — Explain Selection, when there is a selection.
Editor right-click menu — Explain Selection (with a selection), Ask About This File, Add File To Base Context, Attach File To Chat, and File a Ticket.
Explorer right-click menu — Ask About This File, Add File To Base Context, Attach File To Chat.
Files on disk#
| Path | Contents |
|---|---|
.blacksite/base-context.json |
Curated topics and file references |
.blacksite/planning.json |
Plans, phases, and state |
.blacksite/plan-runs/ |
One folder per plan run: its ledger and event log. Gitignored |
.blacksite/tickets.json |
Ticket queue, links, comments, and activity history |
.blacksite/reference/<sessionId>/ |
Files attached to a conversation |
.blacksite/ (other) |
Codebase index, map notes, execution logs, embedded database |
See Plans & Context for what is worth committing.