Configuration

All settings are under the sidecar.* prefix. Open VS Code settings (Cmd+, / Ctrl+,) and search for “sidecar”.

Connection

Switching backends (recommended)

You don’t have to edit these settings by hand. Click the ⚙ gear in the chat header and pick a backend from the Backend section of the settings menu — SideCar’s built-in profiles flip baseUrl, provider, and model in one click:

Each profile stores its API key in its own SecretStorage slot (sidecar.profileKey.<id>), so switching between profiles preserves keys you’ve already entered — setting your Anthropic key once won’t clobber your OpenAI key, and vice versa. The currently active profile is checkmarked in the menu. The same flow is available from the Command Palette as SideCar: Switch Backend.

On first switch to a profile that needs a key, SideCar will surface a warning with a “Set API Key” button that chains into the standard SideCar: Set API Key flow — the key is stored under the correct profile slot automatically.

For custom setups (non-standard ports, Anthropic-compatible proxies, etc.) the settings table above is still the right path — the profile switcher only covers the built-in providers.

Provider auto-detection

When sidecar.provider is auto (default), SideCar detects the backend from the URL:

• localhost:11434 → Ollama (native API)
• anthropic.com → Anthropic (Messages API with prompt caching)
• localhost:11435 → Kickstand — reads bearer token from ~/.config/kickstand/token automatically
• Everything else → OpenAI-compatible (/v1/chat/completions)

Set sidecar.provider explicitly if auto-detection doesn’t match your setup — for example, if you’re running an Anthropic-compatible proxy on a custom URL, or a local Kickstand dev build on a non-standard port.

API key storage (SecretStorage)

API keys are stored in VS Code’s SecretStorage, not in plaintext settings.json. This applies to both sidecar.apiKey and sidecar.fallbackApiKey.

Setting or refreshing your key:

Three equivalent ways to set or rotate your key:

1. Open the command palette (Cmd+Shift+P / Ctrl+Shift+P) and run SideCar: Set / Refresh API Key.
2. Click the $(key) icon in the chat view’s title bar.
3. Let a native error toast prompt you — when an auth error fires, the Set API Key action button on the toast runs the same flow.

A password input prompt appears. Values are trimmed of whitespace on save (defense-in-depth trim also fires at the AnthropicBackend constructor, in case an existing stored key has a stray newline from an earlier paste). Empty input is rejected with a warning. The value is stored encrypted in your OS keychain (macOS Keychain, Windows Credential Manager, or libsecret on Linux). After saving, SideCar automatically refreshes the model list so the UI recovers from any “Cannot connect” error state without requiring a window reload.

Migration from plaintext:

If you previously set sidecar.apiKey in settings.json, SideCar automatically migrates it to SecretStorage on first activation:

1. Reads the plaintext value from settings.json
2. Stores it in SecretStorage
3. Clears the plaintext value from settings.json

After migration, the setting in settings.json will be empty (or back to the default "ollama"), and the actual key lives in SecretStorage.

Why this matters:

• API keys never appear in settings.json — safer when sharing settings, dotfiles, or screenshots
• Per-machine isolation — settings sync won’t push your keys to other devices
• Standard OS-level secret storage instead of plaintext on disk

The fallback API key (sidecar.fallbackApiKey) follows the same pattern but does not have a dedicated command — set it via settings.json once and it migrates automatically on the next activation.

Agent behavior

Context

Context pinning

Pin files or folders so they’re always included in context, regardless of relevance scoring:

"sidecar.pinnedContext": ["src/config/settings.ts", "src/agent/"]

You can also pin files dynamically in chat using @pin:path:

@pin:src/types.ts How does the ContentBlock type work?

Pinned files appear in a dedicated “Pinned Files” section before relevance-scored files.

Large file & monorepo handling

Streaming reads

For large files exceeding streamingReadThreshold, SideCar automatically uses summary mode:

• Reads first N lines (default 50)
• Reads last M lines (default 30)
• Shows omitted line count in the middle

This keeps context focused on the structure and key parts of files without loading entire file content.

Multi-root workspaces

Pin specific workspace roots for monorepo development:

"sidecar.workspaceRoots": ["/path/to/repo/packages/core", "/path/to/repo/packages/ui"]

This is useful for:

• Monorepos: focus indexing on the sub-projects you’re actively working on
• Multi-root workspaces: reduce context noise by excluding irrelevant projects
• Large codebases: improve startup time by indexing only relevant directories

If not set (default), SideCar indexes all workspace folders.

Depth limiting

For deeply nested projects, limit traversal depth to prevent context bloat:

"sidecar.maxTraversalDepth": 5

Files deeper than this level are excluded from workspace indexing, reducing noise in large projects with many nested directories.

Ignoring patterns

Create a .sidecarignore file in your workspace root (same format as .gitignore):

# Ignore build artifacts
dist/
build/
.next/

# Ignore dependencies
node_modules/
venv/

Patterns from .sidecarignore are merged with default excludes (.git, .sidecar, node_modules, etc.).

Auto-fix

When enabled, SideCar automatically runs VS Code’s language diagnostics after the agent writes or edits a file. If errors are found, they’re fed back to the model to self-correct — up to the configured retry limit.

Completion gate

When enabled, SideCar tracks every write_file / edit_file call against every run_tests / eslint / tsc / vitest / jest / pytest / npm test invocation during the turn. At the natural termination point, if any edited source file has a colocated .test.ts / .spec.ts that wasn’t exercised, or if lint never ran, the gate injects a synthetic user message into the loop demanding the checks before the turn can end. Capped at 2 injections per turn to prevent loops — after exhaustion the loop terminates with a warning rather than hanging.

This catches the failure mode where the model reports a change as “ready for use” without ever running the checks it claims pass. See Agent Mode → Safety guardrails for the full mechanism.

Background doc sync

JSDoc sync scans the leading JSDoc block for every top-level function / arrow-const declaration and compares each @param entry against the signature. Orphan tags (tags with no matching parameter) and missing tags (parameters with no documentation) surface as warning diagnostics. Two quick fixes are offered per finding: “Remove orphan @param” and “Add missing @param” — both preserve the JSDoc block’s indentation and * prefix. Functions with destructured or rest parameters are skipped.

README sync scans fenced ts / tsx / js / jsx / typescript / javascript code blocks in README.md for direct calls to workspace-exported functions. Exported functions are indexed from src/**/*.{ts,tsx,js,jsx} on activation and refreshed incrementally on file save / create / change / delete, so README drift surfaces immediately after you rename or change a function signature. Quick fix rewrites the call to match the signature: drops trailing arguments when there are too many, or appends the missing parameter names as placeholders when there are too few. Method calls (obj.foo(...)), constructor calls (new Foo(...)), and control-flow keywords (if (x), while (y)) are excluded. Only single-line call expressions with no nested parens in their arguments are checked — nested or multi-line calls are silently skipped rather than mis-flagged.

Spending budgets

Set spending limits to prevent runaway costs when using paid APIs (Anthropic, OpenRouter). When a budget is active:

• At 80% usage: a warning message appears in chat before the agent run starts
• At 100% usage: the agent run is blocked with a message indicating which setting to adjust

Budget tracking uses the per-run cost estimates stored in metrics history. View current spending with the /usage command, which shows a Budget Status table with spent/limit/remaining for each active budget.

Budgets reset on calendar boundaries — daily at midnight local time, weekly on Monday midnight.

Cost controls (paid backends)

Four additional settings that pair with the spending budgets above to drive down the cost of agent runs on Anthropic / OpenAI. See the Cost controls section in the README for the full rationale.

Session spend tracker is not a setting — it’s always on for Anthropic requests when they return usage data. The $(credit-card) $0.12 status bar item shows up the moment a paid backend incurs cost. Click it for a per-model breakdown. Manage via:

• SideCar: Show Session Spend — QuickPick with totals, request counts, and per-model token breakdown
• SideCar: Reset Session Spend — clear the tally (does not affect the Anthropic-side totals in their Console)

The price table is a hardcoded best-effort at list prices for Claude Opus 4.6/4.5, Sonnet 4.6/4.5, Haiku 4.5, and the 3.x fallbacks. Enterprise and committed-spend discounts are not reflected. Use the Anthropic Console for authoritative monthly totals.

Inline completions

Shell execution

Since v0.59, agent shell commands (run_command, run_tests) render live in a reusable SideCar Agent terminal via VS Code’s shell-integration API rather than in a hidden subprocess. Benefits: transparency (you see exactly what the agent runs), SSH / Dev Container / WSL / Codespaces correctness (shell integration inherits VS Code’s remote shell session instead of escaping to the host), and proper exit-code capture. If shell integration isn’t available on your shell, the ShellSession fallback kicks in automatically — it’s a persistent shell session with environment variables, cwd, and aliases persisting between tool calls. Set a longer timeout for builds and installs. Use background: true to start long-running processes and check on them later with command_id.

Shadow Workspaces (v0.59+)

Optional sandbox for agent tasks. When enabled, the agent runs in an ephemeral git worktree at .sidecar/shadows/<task-id>/ off the current HEAD — writes never touch your main working tree until you accept the resulting diff.

At task completion, SideCar shows a showQuickPick with the diff summary (file count, line count) and an Accept / Reject choice. Accept applies the diff to main as staged changes (so you see them in git status). Reject discards the shadow and leaves your main tree untouched. The v0.59 MVP uses an accept-all / reject-all prompt; per-hunk review UI, conflict handling, symlinked build dirs, and /sandbox <task> slash command wiring land in v0.60+.

SIDECAR.md Path-Scoped Section Injection (v0.67+) + Retrieval Mode (v0.92+)

Pre-v0.67, the entire SIDECAR.md body landed in every agent turn’s system prompt and got mid-chopped on overflow. v0.67 replaces that with a deterministic, path-aware selector that routes sections by <!-- @paths: glob --> sentinels. v0.92 adds a third mode — retrieval — for large SIDECAR.md files where path-scoped routing is either unannotated or too coarse.

See SIDECAR.md for the sentinel schema.

Retrieval mode detail: on first use (or after a content change), each section body is embedded with all-MiniLM-L6-v2 and persisted to .sidecar/cache/sidecarMd/. Subsequent turns only re-embed sections whose content changed. The SidecarMdRetriever joins the existing RRF fusion pipeline alongside DocRetriever, SemanticRetriever, etc. — so SIDECAR.md sections compete on the same relevance footing as project knowledge and documentation.

Fork & Parallel Solve (v0.67+)

Spawns N parallel approaches to the same task in isolated Shadow Workspaces, then picks the winner. See Slash Commands — Fork.

Every fork forces forceShadow: true, deferPrompt: true regardless of sidecar.shadowWorkspace.mode — the user’s main tree is untouched during the run and no mid-run quickpicks fire. The aggregated review runs once every fork settles.

Typed Sub-Agent Facets (v0.66+)

Dispatchable specialists — general-coder, test-author, security-reviewer, latex-writer, signal-processing, frontend, technical-writer, data-engineer, plus project + user overrides. See Agent Mode — Typed Sub-Agent Facets and Extending SideCar — Facets for the dispatch flow and schema.

Built-in facets are embedded in the extension and always available — no disk I/O, no broken-unpack footgun. Disk facets with an id matching a built-in override the built-in; duplicate ids across disk sources surface as load errors without aborting the rest of the registry.

Debugging & reasoning

Since v0.45.0, reasoning is rendered as a numbered timeline: each thinking block closes out when a tool call starts, producing discrete steps with purple pills (reasoning) or blue pills (tools) and a duration badge per step. Longer-running steps show elapsed time; sub-500ms steps hide the badge to reduce visual noise.

Chat UI

Three settings control chat UI density, font size, and accent color. All three update live — changing them in Settings takes effect immediately without a reload.

Accent color values pass through an allowlist CSS-color validator before being written to the DOM as a custom property, so settings strings can’t smuggle additional style declarations into the chat.

Terminal error interception

SideCar watches the integrated terminal for commands that exit with a non-zero status. When it detects a failure it shows a Diagnose in chat notification; accepting injects a synthesized prompt containing the command, exit code, working directory, and the ANSI-stripped tail of the output, then runs the agent against the failure.

Requirements: VS Code 1.93+ with shell integration active. POSIX shells (bash, zsh, fish) and PowerShell are supported natively; other shells may need manual shell integration setup. When shell integration is unavailable the watcher silently no-ops — the setting itself is harmless.

Dedup: Identical command lines within a 30-second cooldown window fire only once, so a retry loop of npm test won’t spam notifications.

Ignored terminals: SideCar’s own SideCar terminal is always skipped to avoid feedback loops when the agent runs shell commands.

Semantic Search

SideCar uses ONNX embeddings for semantic file search — queries like “authentication logic” find src/auth/jwt.ts even without keyword matches in the file path or conversation history.

The embedding model (all-MiniLM-L6-v2, 384-dimensional, quantized) loads in the background after the workspace is indexed. Until it’s ready, SideCar falls back to keyword-based scoring. Embeddings are cached in .sidecar/cache/embeddings.bin and only recomputed when file content changes.

RAG & Agent Memory

SideCar uses Retrieval-Augmented Generation (RAG) to inject relevant documentation into the agent’s context, and persistent memory to track learned patterns across sessions.

RAG Configuration

Documentation is automatically discovered in:

• Project root: README*, ARCHITECTURE*, DESIGN*
• Directories: docs/**, doc/**, wiki/**
• All .md files in these locations are indexed and searchable

When a user sends a message, SideCar searches the indexed documentation for relevant sections using keyword matching. Matching entries are injected into the system prompt to improve accuracy.

Example: If you ask “how does authentication work?”, and there’s a docs/AUTHENTICATION.md with relevant content, it’s automatically included in the context.

Agent Memory Configuration

Agent memory tracks:

• Patterns: Tools that work well for specific problem types
• Decisions: Coding conventions and architectural choices
• Conventions: Project-specific patterns and established practices

Memory is persisted to .sidecar/memory/agent-memories.json and automatically loaded when SideCar starts. Each memory entry includes:

• Timestamp of when it was learned
• Use count (incremented each time referenced)
• Category for organization

Example: After the agent successfully uses formatAuthorName() for a specific task, it’s remembered. When a similar task is encountered later, the memory is retrieved and injected, improving consistency.

Memory is also recorded during agent runs whenever:

• A tool is successfully executed (success pattern recorded)
• New coding conventions are applied
• Project decisions are made

Extensibility

Custom tools example

"sidecar.customTools": [
  {
    "name": "deploy",
    "description": "Deploy the application to staging",
    "command": "npm run deploy:staging"
  }
]

Custom tools appear alongside built-in tools and go through the same approval flow.

macOS Seatbelt Sandbox (v0.89+)

Wraps agent run_command and run_tests calls with /usr/bin/sandbox-exec on macOS. The deny-default SBPL profile allows reads everywhere, network-outbound, and writes only inside the workspace root, /tmp, and common build caches (~/.npm, ~/.cargo, ~/.gradle, ~/.m2). Automatically disabled on Linux and Windows where sandbox-exec is unavailable.

External Context Providers (v0.89+)

Pull live issue-tracker context into every agent system prompt. At the start of each turn SideCar fetches the configured trackers, injects an ## Active Issues block, and caches results for 5 minutes. Errors (bad token, network failure) are non-fatal — a ⚠️ line appears in the block but the turn continues.

GitHub Issues example:

"sidecar.contextProviders": [
  {
    "type": "github",
    "filter": "assigned",
    "maxIssues": 5
  }
]

The GitHub provider auto-detects owner/repo from git remote get-url origin. For Linear and Jira supply apiKey and optionally teamId / projectKey.

Model Arena (v0.90+)

Side-by-side streaming comparison of 2–4 models on the same prompt, with a local ELO leaderboard. See Slash Commands — Model Arena for the full flow.

ELO ratings are persisted to .sidecar/arena/elo.json (K=32, multi-way pairwise) and accumulate across both chat and agent arena runs.

Dependency Drift Alerts (v0.91+)

Scans package.json, requirements*.txt, Cargo.toml, and go.mod for outdated dependencies and known vulnerabilities. Findings appear in the VS Code Problems panel (source: sidecar-deps) — Information for outdated, Warning for medium/high vulnerabilities, Error for critical. File watchers trigger a debounced (2 s) re-scan on manifest save. See Security Scanning — Dependency Drift for details.

Force an immediate workspace-wide scan with SideCar: Scan Dependencies for Drift & Vulnerabilities from the Command Palette, or call the check_dependencies agent tool directly.

Code Profiling (v0.93+)

The profile_code agent tool auto-detects the project ecosystem and runs the appropriate profiler, returning the top-N CPU hotspots as ranked markdown. Disabled by default to avoid unexpected shell executions.

Ecosystem detection (first match wins): package.json → Node.js, requirements.txt/pyproject.toml/setup.py → Python, Cargo.toml → Rust, go.mod → Go. Override with ecosystem="node|python|go|rust".

Node.js and Python require a script parameter pointing to the entry file (e.g. profile_code(ecosystem="python", script="src/main.py")). Go and Rust use their built-in bench runners and need no script.

LaTeX Agentic Debugging (v0.94+)

The latex_compile agent tool compiles a .tex document and returns structured errors and warnings with file and line references. Disabled by default.

The tool auto-detects the main .tex file in the workspace root; pass file="path/to/main.tex" to target a specific document. latexmk is probed at each call and falls back to pdflatex if not installed.

Persistent Executive Function (v0.94+)

When enabled, the agent checkpoints its task state to .sidecar/plans/active.json after each iteration. If VS Code closes mid-run, the next activation prompts you to resume or discard the interrupted task.

Checkpoints older than 24 hours are automatically discarded on the next activation.