Fireball Sidecar for Vscode
The first-party Vscode client for Fireball Sidecar,
with streaming AI chat, workspace-aware tools, approved file edits and command execution, and
usage/cost visibility, in Vscode's Secondary Sidebar.
Capabilities
Chat
- Standalone Sidecar chat beside other AI clients in Vscode's Secondary Sidebar
- One Fireball sign-in (shared OAuth Hosted UI) — Fireball Sidecar: Sign In; tokens in
Vscode SecretStorage, refreshed silently
- Auto (server-routed) or a manual model pick, based on the signed-in Sidecar tier
- Streamed responses with cancellation and mid-response steering
- With Remote Control on, a run waiting on an approval (command, file change, web search, "Continue?")
can also be answered from your phone; whichever answer comes first wins, and "Hold" just keeps it
waiting. Without a connection it stays a normal on-screen prompt.
- Image input by pasting into the composer or the "⇧ Upload image" menu item — sent inline with the
message, nothing stored server-side
- Markdown headings/lists plus syntax-highlighted fenced code blocks with copy controls; a numbered
list of options the reply invites you to choose from renders as a clickable choice list
- Local recent chats and groups in the empty-chat dashboard, Up/Down prompt history
- Per-response token usage and cost breakdown, plus live 5h/1d/1w/1mo account usage and an
Account page (Usage Report, Bonus Tokens)
Workspace tools — the model can read and act on your own workspace, each gated by an
untrusted-workspace check and, for anything that changes or runs something, explicit approval:
- Read-only:
get_selection, get_open_editors, list_workspace_files, read_file,
get_diagnostics, get_git_status
- Write/execute:
apply_patch (diff preview, WorkspaceEdit on approval), apply_patches
(several files in one call: all validated first, one approval, one WorkspaceEdit) and
run_command (bounded output, timeout, secret redaction)
- A bounded, redacted tool audit log for all eight tools, viewable from the Security menu or the
Command Palette (Fireball Sidecar: Tool Audit Log)
Security menu — three approval sections (Terminal Commands, Web Search, Plan Mode), each
Ask/Auto plus a session-allow toggle; Terminal Commands also has a configurable allow/deny pattern
list with a built-in starter deny list for destructive commands. Plan Mode disables every Run
button until turned back off.
Settings page — Show Work toggle and a 24-swatch Accent Color picker, backed by real
Vscode settings. The Account page shows sign-in status plus Billing and Export Data.
Local Agent — opt-in, private local inference (Microsoft's official Phi-3 Mini, checksum-
verified, downloaded into this extension's own storage, never packaged in the VSIX) for cheap,
bounded work: formatting a completed slash-command result, or a short text-only explain/rewrite/
summarize request. A deterministic router keeps everything else — image input, current/web-search
intent, tool-choosing work, a manual model pick — on Sidecar; a local miss falls back to Sidecar
once, or reports the local failure, per fireball.sidecar.localAgent.fallback. Fireball Sidecar:
Set Up Local Agent / Local Agent Status / Remove Local Agent manage it.
Development
npm ci
npm run check
npm run package
Press F5 from this repository to launch an Extension Development Host. Run Fireball Sidecar:
Sign In (opens the shared Fireball login in a browser), then Fireball Sidecar: Open Chat.
Sidecar also has its own sidebar entry.
The extension talks to the ground-zero platform: the Sidecar API at
https://api.fireballsidecar.com/v1/vscode (chat, tools, history, usage, files, …),
the Enterprise API at https://api.fireballenterprise.com/v1 (devices/register for the signed
entitlement, library?view=profile, account/security, devices), and sign-in through
auth.fireballenterprise.com (the shared Fireball account; OAuth Auth Code + PKCE, public client
sidecar-vscode, scopes openid email profile, completion page
https://fireballenterprise.com/oauth/vscode/callback). Every call carries
X-Id-Token, X-Fireball-Device and X-Fireball-Platform: vscode. Set
"fireballSidecar.environment": "development" in user settings to use the *.dev.* hosts, the
dev pool's client and https://dev.fireballenterprise.com as the OAuth callback page and
entitlement issuer (all in src/platformConfig.ts).
Configuration
Open Gear > Help for the built-in expandable Agent Settings reference, including Available Settings
and settings-source Precedence.
| Setting |
Default |
Purpose |
fireballSidecar.environment |
production |
Fireball platform: production or development (hosts, sign-in and OAuth client together) |
fireballSidecar.apiBaseUrl |
https://api.fireballsidecar.com/v1/vscode |
Override the Sidecar API base; unset follows environment |
fireballSidecar.authDomain |
(blank) |
Override the sign-in domain (auth.fireballenterprise.com / auth.dev.fireballenterprise.com) |
fireballSidecar.oauthClientId |
(blank) |
Override the sidecar-vscode OAuth client id |
fireball.sidecar.showWork |
true |
Show the Terminal/Read/Edit/Web activity box (command, output, routing status) while Sidecar works |
fireball.sidecar.color |
#C61A28 |
Accent color for chat bubbles and the message box border |
fireball.sidecar.terminal.autoApprove |
{} |
Command patterns to always auto-approve or always confirm |
fireball.sidecar.web.mode |
askEachTime |
Whether Sidecar must ask before searching the web |
fireball.sidecar.edits.mode |
askEachTime |
Whether Sidecar must ask before applying a file change (Plan Mode still blocks all edits) |
fireball.sidecar.plan |
false |
Plan Mode — disables Run buttons until turned back off |
fireball.sidecar.plan.report |
false |
While Plan Mode is on, also save each reply to a file |
fireball.sidecar.toolSteps.promptEvery |
200 |
Tool steps on one reply before an inline "Continue?" prompt |
fireball.sidecar.toolSteps.hardMax |
500 |
Absolute tool-step ceiling per reply — always stops here |
fireball.sidecar.allowOutsideWorkspace |
false |
Let Sidecar read/change explicitly-pathed files outside the open folder (still approval-gated) |
fireball.sidecar.localAgent.enabled |
false |
Opt in to Local Agent for cheap, bounded local work |
fireball.sidecar.localAgent.fallback |
bedrock |
bedrock falls back once on a local miss; error reports it instead |
fireball.sidecar.localAgent.maxTokens |
512 |
Max tokens Local Agent may generate for one reply |
fireball.sidecar.localAgent.temperature |
0.2 |
Local Agent's sampling temperature |
Skills are the slash commands
Sidecar reads skills straight from the repository, with no generated copy in between:
.fireball_ai_toolkit/skills/, any repo-local .<repo>/skills/ and the generated mirror .sidecar/skills/, each as a flat
<name>.md or a bundle <name>/SKILL.md (resource files stay beside it). User-level skills live in
~/.sidecar/skills/. A skill's body is the full command text, so /<name> runs it, with its
argument-hint shown in the / menu. Frontmatter: description, argument-hint, hints
(plain-language trigger phrases), instructions (repo-relative files to read and follow), and two
switches that default to true: user-invocable: false hides it from /, and
ai-invocable: false stops hint matching from loading it on its own. Skills merge by name, so each shows once:
repo-local .<repo>/skills > .sidecar/skills (the generated mirror, flat snake_case files such as
add_bug.md) > .fireball_ai_toolkit/skills > user ~/.sidecar/skills. Names dedupe with -, space
and _ treated alike (add-bug = add_bug), the highest layer's spelling is the visible one, and the
other spelling stays a trigger phrase. A skill whose body is only
a "Source of truth" pointer still follows the pointer.
A leftover commands/ directory (.sidecar/commands, .fireball_ai_toolkit/commands) is still read for one more release as slash-only skills, with a warning in
the console; migrate them to skills.
Portable repository and user defaults may also live in .sidecar/settings.yml and
~/.sidecar/settings.yml. Repository values override identical user-file keys, and Vscode
settings.json is the final override for an identical pattern. Any matching false rule still
wins across different patterns.
permissions:
allow:
terminal:
uv run --no-sync inv*: true
git status*: true
rm: false
Every bound in the extension (tool-step budget, output/file size caps, timeouts, session memory)
is catalogued in docs/current_limits.csv.
Manage plan options at fireballenterprise.com/plans.