Settings, Themes & Spending

The Settings panel is a two-column overlay: a left nav listing all sections by group, and the selected section on the right.

Sections are organized into seven groups:

Only two things are hidden by default: the entire Workspace group (Editor, Keybindings, Terminal) and the Experimental item. All other sections - including Agent, QEL, Fleet, MCP Servers, Skills, Custom Agents, Privacy & Safety, and Spending - are always visible.

To see the advanced sections, scroll to the bottom of the left nav and click Show advanced settings. The app remembers this preference.

To jump to a specific setting without scrolling: press Ctrl+F inside the panel to focus the search box. It matches across all 30 sections, and mode is a search term - typing chat or code finds the sections that have been audited for mode relevance.

Which of these apply in Chat Mode? Not the one you'd guess from the grouping. QEL is not mode-gated, agent.dual_model is a silent no-op in chat, and several settings are code-only only because of what happens to reach them. See the Settings by Mode page for the audited list, each claim with the file and line that decides it.

Bodega ships with four themes - two dark, two light:

Theme changes apply to the editor, terminal, and all UI components. No restart needed.

To change the theme:

1. Go to Settings → Theme (top of the nav, always visible).
2. Click any card - it previews immediately.
3. Click Apply Theme to save. If you navigate away without clicking Apply, the preview reverts.

The current active theme is shown in the top-right of the Theme section header.

Settings → Profile (Look & Feel group).

Display name (user.display_name) appears in the greeting on the home screen.

Agent name (persona.name, default: Bodega) shows in chat bubbles, the terminal, and the agent's system prompt. Leaving it blank or whitespace-only falls back to Bodega.

Voice input (STT) adds a microphone button to the chat input bar:

• Provider: Local (Whisper-compatible server) or OpenAI cloud
• If using a local server, enter the server URL
• Model: large-v3 (highest accuracy) or base (fastest)
• Language: 10 options

Air-gap mode blocks cloud STT automatically.

This section also includes a VS Code / Cursor settings import utility for migrating keybindings and preferences.

Coming from another editor? (beta.28) The Import editor rules row scans the open project for Cursor, Copilot, Cline, Windsurf, and Continue rules files and appends them to .bodega-rules - append-only under a dated per-source header, so it never overwrites rules you already wrote, and re-importing skips sources that are already in. Bodega also offers this as a one-time toast when you open a project that has competitor rules.

Confirmation Prompts: the Reset confirmation prompts button re-enables the Fleet discard and apply confirmations you've suppressed with "Don't ask again".

Settings → Models (Models & Providers group) has three tabs:

Discover - browse and download from the curated model catalog.

My Models - assign the model roles that Bodega uses for different tasks:

• Four visible role cards: Default (the fallback for every empty role), Fast, Smart, Agent. Chat, Research, Debug, and Advisor live behind an "Advanced: per-panel overrides" disclosure - same settings keys, just not shown by default. FIM has its own panel lower down the same tab. On a single-model provider (llama.cpp, LM Studio, etc.) the role cards are replaced by one card naming the model actually loaded. The architect/editor pair for Dual-Model Mode is not here: it lives in Settings → Agent
• A hardware tier badge (VRAM + Apple Silicon detection) helps match models to your machine
• FIM (fill-in-the-middle, for code completion ghost text) is configured here
• Codebase Embeddings are also here - not in a separate section. Set provider, model, base URL, and whether to auto-index on project open. A "rebuild needed" banner appears when the saved embedding model differs from what the index was last built with.

Providers - 36 preset connection cards (11 local, 23 cloud, plus a Remote-LAN slot and a Custom OpenAI-Compatible slot). Counted from ProviderPresets.ts; it moves whenever a provider is added, so the tab is the authority. Switching provider takes effect immediately; switching model presets may trigger a server hot-swap.

A search box at the top-right of the Models section filters within whichever tab is active.

Settings → Cloud Boost (Models & Providers group).

Cloud Boost routes individual messages to a secondary cloud provider. It supplements your primary provider - it does not replace it. You opt into it per-message via the chat interface.

Configuration:

• Pick a cloud preset: Anthropic, Azure OpenAI, Cohere, DeepSeek, Featherless, Fireworks, Google Gemini, Groq, Kimi, Mistral, OpenAI, OpenRouter, Qwen, Together - the Boost picker is its own 14-entry list, narrower than the full Providers tab (MiniMax, Z.ai, and the beta.38 additions are primary-provider presets only)
• Paste an API key, optionally override the base URL
• Click Test Connection to populate the model dropdown, then select a default model
• Set daily and monthly budget limits in USD. 0 means unlimited. Requests are blocked when the budget is exceeded.

Spend tracking for Cloud Boost is inline here: the Cost Tracker card shows session / today / monthly spend and request count. It only appears once the backend starts returning cost data (i.e., after your first boosted message).

Air-gap mode disables the Boost toggle and shows a warning banner.

Settings → Cloud API Keys (Models & Providers group, collapsed by default). Click the header to expand.

This section holds BYOK (bring-your-own-key) API keys for using cloud providers as your primary LLM - not for Cloud Boost (which has its own key). Keys are stored encrypted at rest.

Supported providers:

Keys auto-save as you type.

BYOK spend tracking appears at the top of this expanded section as the CloudSpendSummary block - session / today / this month, with a per-provider cost breakdown sorted by spend. It stays hidden until at least one BYOK-charged message has been sent in the current session. Spend figures come from a static pricing table and may differ from your actual provider invoice.

Settings → Spending (Models & Providers group, always visible).

Spending is a dedicated dashboard that consolidates all cost tracking in one place:

• Period picker - switch between 7-day, 30-day, and 90-day views
• Spend chart - a stacked bar chart showing daily spend over the selected period
• Per-provider breakdown - cost and request count per cloud provider
• Per-model breakdown - cost and request count per model
• Data retention control - set how many days of spend history to keep
• Clear All button - wipes all stored spend history

Both Cloud Boost costs and BYOK costs appear here. You do not need to look inside Cloud Boost or Cloud API Keys for cost summaries - Spending is the single place for all billing data.

Pre-send estimate (beta.28): on cloud models, the Code-mode status bar shows roughly what your next message will cost ("~$0.012/msg") next to the Context meter - priced from the current context plus a typical reply. Local models show nothing; there's nothing to pay. The actual per-message cost still arrives after each send.

Settings → Agent (AI Behavior group - always visible).

Controls for the agentic loop:

• Max Iterations (agent.max_iterations, range 5–100) - the starting tool-call budget per message; the loop extends it while progress continues, up to agent.max_iterations_ceiling (default 200), and stops a run early when it stops making progress. The stored default is 50. The number input falls back to 25 when it can't read a saved value, so don't take the box as evidence of what the loop is using; the setting is the authority.
• Tool Timeout (agent.tool_timeout_ms, range 10–300 seconds, default 30) - how long to wait before timing out a tool call

Sub-agents (same section, all off by default): Sub-agents (agent.subagents_enabled) lets the agent hand focused tasks to other agents with spawn_agent; Per-sub-agent Spend Cap (agent.subagent_spend_cap_usd, default 1); Sub-agents in unattended runs (agent.subagents_headless) for the CLI, Loops and background runs; Sub-agents may use the shell (agent.subagent_shell_opt_in), worktree sub-agents only. None are project-config settable. Full story on the Sub-agents page.

Dual-Model Mode splits each loop into two stages: an architect model that plans and an editor model that executes. You pick each model independently. If you assign the same model to both roles, the UI warns you.

Dual-Model only applies in Code mode. Once enabled here, the Dual-Model Verify option in Experimental becomes available.

An informational block in this section explains how the loop works: tool result cap (16,384 chars), context auto-compact threshold, and temperature scaling across iterations.

Auto context-compaction. A long run now trims its own conversation history before it hits the wall, instead of waiting for the hardcoded 85% emergency point or a manual /compact. The llm.auto_compact_threshold setting (default 75) is the fill-percentage at which the loop compacts proactively at an iteration boundary; set it to 0 to disable proactive compaction and leave only the 85% emergency backstop, or to any value from 50 to 95. Compaction is unchanged otherwise - the summary is pinned as a stable system message so it doesn't break the model's cache, and it falls back to mechanical trimming if the summary call fails.

All agent fields save together via Save Agent Settings.

Auto-approve read-only tools (beta.28, off by default): in Ask mode, tools that only read - code search, grep, glob, symbol lookup, and the Map / memory / knowledge / session queries - can skip the approval prompt. The allowlist is by explicit tool name and fails closed: a tool not on the list keeps asking. File writes, web access, and shell are never auto-approved (shell structurally can't be), and Plan mode is untouched.

Settings → Routing (AI Behavior group - always visible).

User-configurable model routing: ordered rules (first match wins) that decide which model handles each request by mode, ask type, agent step, file path, message size, or today's cloud spend. The section also hosts the built-in heuristics (Smart Auto and the chat classifier) as toggleable default rules, your custom classifier patterns, any read-only rules the open project ships in .bodega/config.json, starter recipes, JSON import/export, and a dry-run tester.

Full walkthrough on the Model Routing docs page.

Settings → Prompts (AI Behavior group - always visible).

System prompt templates define the agent's identity, tone, tool policy, and output formatting. The app ships with built-in templates; you can create, edit, and delete custom ones. The built-in Uncensored template is for models you chose because they answer without refusals - it drops Bodega's own decline instruction and keeps truthfulness and privacy; pick it as the Chat default when running such a model.

• Set separate defaults for Chat mode and Code mode using the two pickers at the top of the section
• The active mode's default applies automatically when you switch modes
• Filter by All / Built-in / Custom
• Export custom templates as JSON; import from JSON
• Built-in templates can be toggled on/off but not edited or deleted

All three are under the Workspace group (requires Show advanced settings).

Settings → Editor

• Font size, font family, tab size
• Word wrap, minimap, line numbers, whitespace rendering
• Bracket pair coloring, font ligatures
• Format on save
• AI completions (FIM ghost text) - enable/disable

Settings → Keybindings View the built-in keyboard shortcuts for navigation, editing, and terminal actions.

Settings → Terminal

• Font size, cursor style (bar / block / underline), cursor blink
• Scrollback buffer size

Terminal changes take effect for new tabs only. Existing terminal tabs keep the settings they opened with.

Settings → MCP Servers (Integrations group - always visible).

MCP (Model Context Protocol) lets external servers expose additional tools to the agent. Bodega supports multiple simultaneous MCP server connections.

Each server card shows:

• Colored status dot (green = connected, red = disconnected)
• Name, network badge, tool count
• Connect / disconnect toggle and Remove button
• Command string and exposed tool names

The list auto-refreshes every 5 seconds. Errors appear as red text below the server row.

Adding a server:

1. Enter Name, Command, and Arguments.
2. Check Requires network access if the server makes outbound requests.
3. Click Add Server.

Quick-start presets (Filesystem, GitHub, Brave Search, SQLite, Memory, Fetch, Sequential Thinking) fill the form automatically.

Once connected, tools appear in the agent's tool list as mcp_<servername>_<toolname>. Servers marked as requiring network access are blocked when air-gap mode is on.

Per-server tool filtering: each server can carry an allowlist (enabledTools - expose only these raw MCP tool names) and/or a denylist (disabledTools - expose all but these). The allowlist wins: when it's non-empty only those tools are considered, and the denylist then subtracts from whatever remains. An empty allowlist means "all tools". Filtering only ever narrows what security already permits - it can't grant a tool back.

Required servers (fail-fast): mark a server required and a failed connect at boot is surfaced loudly (error log + status broadcast) instead of being silently retried. The default behavior keeps quietly retrying in the background.

Settings → Skills (Integrations group - always visible).

Skills are reusable agent workflows. They're triggered by slash commands in the chat bar or automatically when Bodega detects a matching keyword pattern (auto-activation).

• Global auto-activation toggle - turn off if you want slash-command-only invocation
• Filter by All / Built-in / Custom
• Built-in skills can be toggled on or off but not edited
• Custom skills: create via the form (name, description, triggers, tools, invocation type, body), edit, delete
• Reload button rescans the filesystem for skill files

Each skill card shows its triggers, tools, and invocation type.

Settings → API Server (Integrations group - always visible).

Enables a local server that accepts OpenAI-compatible requests, so tools like Claude Code or Continue can route through Bodega's local models.

Three endpoints when enabled:

• GET /v1/models
• POST /v1/chat/completions
• POST /v1/agentic/completions

Default port: 1337. An optional API key enforces Bearer token auth.

The Quick Setup block shows pre-filled environment variable snippets for Claude Code and other clients.

Requires an app restart to take effect. The base URL and API key can be copied via the buttons in the section.

Settings → Privacy & Safety (Privacy & Safety group - always visible).

Air-Gap Mode - blocks agent web tools (web_fetch, web_search), shell network commands, auto-updates, cloud STT, Cloud Boost, and MCP servers requiring network access. It does NOT block LLM provider traffic. If a cloud provider is set while air-gap is on, a warning banner appears.

Guardrails:

• Content filtering master toggle
• Custom blocked patterns (one regex per line, with per-line validation)
• Shell command sandbox level (applies in Act mode only - shell never auto-approves in Ask or Plan mode, whatever this is set to):
  • Off - every command waits for you
  • Moderate - read-only commands (ls, cat, echo, git status, …) auto-approve after 30 seconds
  • Strict - nothing auto-approves; every command waits for you, including read-only ones

The sandbox level applies in Act mode only. Shell commands never auto-approve in Ask or Plan mode.

Smart approval (off by default). In Ask mode, a low-risk read-only tool call that clearly matches what you just asked for can auto-approve itself instead of prompting you. Write tools (shell, file writes, str_replace) are always hard-blocked from auto-approval, and the classifier runs after every security gate - it can only reduce prompts, never widen access. Enable with permission.smart_approval and tune the confidence bar with permission.smart_approval_confidence_threshold (default 0.80). See the Privacy & Security docs page for the full security posture.

Rate limits:

• Max Input Length (100–100,000 chars)
• Messages Per Minute (1–200)
• Session Token Budget (1,000–1,000,000 tokens)

Save all fields together via Save Safety Settings.

Both are under the AI Behavior group (always visible).

Settings → Session Memory

• Toggle memory persistence (whether long-term memories survive restarts)
• Short-term capacity: 100–50,000 entries (cleared on restart)
• Long-term capacity: 100–100,000 entries (persisted to SQLite)
• Current entry count shown live
• Add topic/fact pairs manually; browse, search, and delete stored memories

Settings → Knowledge Base

• Add entries by URL (Bodega fetches and stores stripped text) or raw Text (large content is auto-chunked)
• Tags organize entries; click a tag to filter
• Search by title, content, tags, or URL
• Expand any entry to read its full content; delete via the X button
• Knowledge & Embeddings: enable embedding-based semantic search for knowledge entries, choose embedding model and provider, adjust hybrid search weight (0 = keyword only, 1 = semantic only)
• The agent searches knowledge automatically via the query_knowledge tool

You can also add knowledge from the chat + menu (Add URL) or from the Context Inspector (Add Knowledge button) without opening Settings.

Settings → Accessibility (Look & Feel group - always visible).

Focus Style: Default / Bold (3px outline) / High Visibility (yellow outline)

The section also documents keyboard navigation patterns and ARIA / screen reader support.

Settings → Experimental (About & Support group - requires Show advanced settings). All features carry a yellow warning banner.

Dual-Model Verify - after each agentic loop iteration, the architect model reviews the editor model's output. Requires Dual-Model Mode to be enabled in Settings → Agent - the toggle is disabled if it isn't.

The Language Server (LSP) toggle graduated out of this section: the server now ships with Bodega, and the setting lives in Settings → Editor → AI Features. Smart Auto also moved out of Experimental: it now lives in Settings → AI Behavior → Routing as a built-in, toggleable routing rule (llm.smart_auto), alongside the chat classifier and your own ordered rules.

Settings → About (About & Support group - always visible, no Show advanced settings required).

• App version info
• Export Diagnostics Bundle - writes a redacted system snapshot to a text file. Includes version, hardware, settings (secrets stripped), recent sessions, recent errors, network activity, and backend logs. If llama-server has crashed, the bundle also carries its last exit status and the error text llama-server itself printed, which is usually the fastest way to tell a port conflict from an out-of-memory load. Useful for bug reports.
• Reset to Defaults - wipes all settings. This cannot be undone.

A project can ship a .bodega/config.json that overrides some of your settings when that project is open. It is a deliberately narrow list, because a repo you cloned must not be able to change how Bodega behaves on your machine.

The 22 keys a project config may set:

Anything else in the file is silently ignored. That is not an oversight - several settings are global-only on purpose and were kept off this list, or removed from it:

• mixture.* - so a repo can't fan your prompt out to cloud providers or choose which models see your code
• boost.* - so a repo can't spend your money
• llamacpp.custom_args - so a repo can't change how your local server starts
• shell.env_policy - so a repo can't widen shell exposure
• agent.deferred_tools - so a repo can't reshape the model's tool surface
• llm.smart_auto and llm.qel_auto_escalate - these were on the list and were taken off, precisely because a committed config could otherwise flip your model selection and spend behaviour without you noticing

Two behaviours worth knowing:

• llm.routing_rules does not shadow your global rules - it stacks above them. Unlike every other key here, project rules are concatenated in front of yours rather than replacing them.
• The whole file is inert until the workspace is trusted. An untrusted or not-yet-evaluated project path reads back exactly as if .bodega/config.json did not exist. It fails closed, not open.