Getting Started

Two modes share a single window:

• Chat mode (Ctrl+1) - conversational AI. Questions, research, quick tasks. No file tree, no AI panels.
• Code mode (Ctrl+2) - full IDE. Monaco editor, file tree, four AI panels (Agent, Research, Debug, Advisor), and a terminal.

The mode toggle is in the top bar. The agent's name defaults to Bodega and is configurable in Settings → General → Profile. The gear icon opens Settings. The hamburger menu (top-left) gives access to Help, keyboard shortcuts, and onboarding controls.

Bodega never sends data to any server unless you explicitly configure a cloud provider. Air-gap mode enforces this at the network layer.

Is it open source? Not today. Bodega One is free to download and use while it is in public beta, including at work. The source code is the Bodega One team's own while the open-source decision is being made; until then, please do not redistribute, resell or rebrand it. No date is promised for that decision.

The first time you open Bodega, two things happen in sequence:

1. Setup - the first screen asks How do you want to run Bodega One? with three choices: On this computer, With a cloud key, or Offline only (air-gap). While you decide, Bodega only looks at this machine: it scans the default ports of local providers (Ollama, LM Studio, vLLM, llama.cpp) and reads your GPU and VRAM. Nothing leaves the machine until you press Continue. A running provider preselects On this computer ("Ollama found · 3 models"); so does a GPU with 6 GB or more. A cloud key you already saved preselects With a cloud key. With no GPU, nothing is preselected and both rows say so plainly: local models will be slow, and a free cloud tier works without a GPU. Offline only turns on the global air-gap setting before anything else runs. Skip setup finishes without a model; you can connect one later from the status bar, and setup does not reopen on the next launch. After Continue, On this computer uses a provider that is already running (one provider with one model finishes straight away), or offers the managed llama.cpp install; detection has a 12-second hard ceiling, with a Skip link after 8 seconds. Downloads show their size first and an estimate of the time left only after about five seconds of measured transfer. Once a model is ready, the last screen offers Open a project folder (the folder opens, and its trust prompt appears, after setup closes), Bring settings from VS Code / Cursor when any were found on this computer, and Show me around (1 min), checked by default. Picking a local model now shows one recommended card ("Install and start chatting", with the server's stated reason) instead of a full list up front - the full list and quant chips move behind a Choose a different model reveal. Before the download starts, the offer screen names the actual runtime build and size it resolved (e.g. "RTX 5090 · CUDA 13 build · 513 MB") instead of a generic size range. Ollama's own first-run download screen shows GB-of-GB and a bytes/s rate rather than an unlabeled spinner.
2. Quick tour - if Show me around was left checked, a 5-step spotlight tour starts as soon as setup closes, before you type anything: Chat & Code, the message box, the model selector, where Settings live, and where to reopen the tour. Everything else is a one-time hint the first time you reach it: Code Mode layout (the first time you are in Code Mode with a folder open), Settings (the first time you open Settings), and Preview, Fleet and Vision as before. Each hint offers the tour or Don't show, which is remembered. Entering Code Mode without a folder shows a small card explaining that Code Mode works in a folder, with Open folder… and Not now. If you already completed the old first chapter, the quick tour is not offered again.
3. A one-time warm-up prompt - once a local model finishes installing, onboarding sends it one short prompt and reports the measured tokens/second before you start chatting, so the first number you see reflects your own hardware rather than a marketing figure.

There is no floating onboarding checklist. A bottom-right card that tracked setup milestones existed once but was removed 2026-05-07 - the guided tour was judged to cover the same ground more clearly and the auto-checking card felt redundant once the tour was polished (see the "OnboardingChecklist removed 2026-05-07" comment in App.tsx, near the GuidedTourOverlay mount). If you click Skip during the wizard, you can re-run everything from the hamburger menu.

The window remembers its size and position. Bounds and maximized state are saved as you resize or move the window and restored on the next launch, validated against your current display so a window that was on a monitor you've since disconnected doesn't open off-screen.

First paint no longer flashes black. The window shows a lightweight skeleton immediately instead of a blank/black frame while the real UI finishes loading.

Native taskbar/dock activity. While a chat stream, a Fleet/background session, or a sub-agent is running, the taskbar (Windows) or dock (macOS) icon shows indeterminate progress. If a background run or sub-agent finishes while the window isn't focused, the icon badges and flashes once - gated on the same Notify when a background run finishes setting (fleet.notify_os, on Settings → General → Notifications) that controls OS notifications elsewhere, since this doesn't have its own separate toggle. Alerts for the chat you are in: Settings → Automations → Background runs → When you're away from the window has two switches, both off by default. Tell me when a reply finishes and Tell me when it needs my approval each flash the taskbar and show a notification when that happens while Bodega One is in the background. Nothing fires while the window is focused.

Two separate re-entry paths live in the hamburger menu (top-left three-line icon) under the Help section:

• Take Guided Tour - replays the core chapters (A → B → C, 17 steps) in sequence from the start. Setup does not re-run. (Settings → About has a picker for replaying one chapter, including the quick tour, on its own.)
• Run setup again - reopens setup from the first screen (How do you want to run Bodega One?), with a running provider or a saved cloud key preselected again. It does not reset the tour: replay that with Take Guided Tour.

Setup timing: Settings → About → Setup timing shows how long each step of your setup took. It is kept on this computer only; Copy setup report puts it on the clipboard if you want to paste it into a bug report.

The old FAQ said "Settings → General → Reset Onboarding" - that path does not exist. The correct path is the hamburger menu.

Choose Offline only (air-gap) on the first setup screen. Bodega One turns on the global air-gap setting before anything else runs, and from then on makes no outbound connections. The per-project Air-Gap Vault stays separate and opt-in.

The next screen lists only what is already on this computer:

• a running local provider (Ollama, LM Studio and the other local presets) with its models - Use this model
• llama.cpp models already added to Bodega One
• GGUF files in your Hugging Face cache
• Point to a .gguf file… to add a file from anywhere on disk. It is checked first: it must be a real .gguf model (not a vision add-on), not a shortcut, not still downloading, and on this computer (a file on a network share is refused, since reading it would use the network).

Running a .gguf file needs the llama.cpp engine installed. It cannot be downloaded offline, so without it the screen says so and a running Ollama or LM Studio is the way in.

No model on this computer yet? Bring one over: on a machine with network access, download a model (in Bodega One, or with bodega models pull <name>), copy the .gguf file here, then use Point to a .gguf file…. Or turn off air-gap in Settings → Privacy & Safety → Air-gap & data to download directly. Open Bodega One anyway finishes setup with air-gap on; setup does not reopen on the next launch.

Bodega supports 38 provider presets: 13 local, 23 cloud, one Remote-LAN slot, and one custom OpenAI-compatible endpoint.

Local (no API key needed): Ollama, LM Studio, NVIDIA PAIR, vLLM, llama.cpp, LocalAI, KoboldCpp, GPT4All, MLX (Apple Silicon), Jan, TabbyAPI, SGLang, Unsloth Desktop

Cloud (API key required): Anthropic, OpenAI, Google Gemini, Groq, Azure OpenAI, Together AI, OpenRouter, Mistral AI, Cohere, DeepSeek, Fireworks AI, Qwen (Alibaba DashScope), Kimi (Moonshot AI), MiniMax, Z.ai (Zhipu), Featherless AI, Concentrate, xAI (Grok), Cerebras, SambaNova, DeepInfra, Novita, Nebius

Gateways: OpenRouter and Concentrate are gateways - one key reaches many upstream vendors. Concentrate serves 172 models from 21 providers, and its model ids are plain slugs (claude-opus-5, gpt-5.6-sol) with no vendor prefix. The picker keeps models from the same upstream together - Anthropic first, then OpenAI and Google - so it opens on the flagship models rather than an alphabetical dump. The blocks are not labelled with the upstream's name, because a bare slug carries no vendor to label them with.

Remote model server (LAN): a model served on another machine on your network over an OpenAI-compatible endpoint. Blocked under Air-Gap mode, which is loopback-only.

Three ways to configure a provider:

• First-run setup - a provider already running on this computer is found and preselected
• Settings → Models & Providers → Providers - click any provider card, enter credentials, click Test Connection, then Set as primary
• Hamburger → Run setup again - reopens setup

Switching providers clears the active model selection to prevent cross-family API errors.

1. Install Ollama from ollama.com and confirm ollama serve is running.
2. Launch Bodega - setup detects Ollama on port 11434, shows "Ollama found" on On this computer and preselects it; press Continue. (With nothing running, setup can also install Ollama for you.)
3. If you're past onboarding: Settings → Models & Providers → Providers → Ollama card → Set as primary.
4. Download models from Models → Discover - click a model card's Download button, or type any Ollama model name in the Pull Any Model input at the top of the Discover tab and press Enter.

Downloaded models appear in My Models automatically. No API key needed.

First-run path:

1. On the first setup screen choose With a cloud key → Continue (if a key is already saved, setup finishes here)
2. Pick a provider from the cloud list (free tiers first)
3. Enter your API key - validation runs automatically against the provider's API
4. On success, the provider is set active

Post-onboarding:

1. Settings → Models & Providers → Providers → find the cloud provider card
2. Enter your API key → Save API Key
3. Click Test Connection → then Set as Active

Each cloud provider has its own key stored separately at llm.<presetId>_api_key. Setting a key for one does not apply to any other. The one exception is the Custom OpenAI-Compatible slot, which falls back to the shared legacy llm.openai_api_key rather than getting a key slot of its own.

With air-gap on, setup preselects Offline only and drops the "set up a cloud provider" shortcuts from the local-model screens. The first screen still lists With a cloud key, but cloud providers need an internet connection and are blocked in air-gap mode.

When llama.cpp is the active preset, Bodega spawns and owns the llama-server process itself - you do not start it. It handles the spawn, bounded crash recovery (up to 3 restarts in a 60-second window), and teardown when the app closes. Requests wait on the manager confirming the model is loaded, not on a port being reachable.

If Bodega can't bring its own server up, it falls back to talking to whatever is already listening at the configured base URL - so pointing the preset at a server you run yourself also works.

First run: choose llama.cpp in the wizard → the LlamaCppOnboarding flow walks through binary install and GGUF selection.

Post-onboarding: Settings → Models & Providers → Providers → llama.cpp card

Managed embedding server (beta.26): for semantic codebase search, you can run a second llama-server on port 8081 for embeddings:

1. Settings → Prompts & Memory → Knowledge base → Advanced → Embeddings → Codebase index
2. Set Provider to llama.cpp
3. Check Let Bodega manage the embedding server
4. Pick an installed GGUF from the dropdown (populated from the same registry as the chat path) or enter a path manually

If no GGUFs are installed yet, the dropdown shows a prompt to download from Models → llama.cpp → Discover. The chat server (port 8080) and embedding server (port 8081) are separate processes.

Hardware detection runs on startup (CPU, RAM, GPU, VRAM). The Discover tab's Fits My GPU toggle filters the catalog to models your hardware can run.

Model dot colors: green = fits comfortably, amber = tight (may use partial CPU offload).

Quick picks by VRAM at Q4_K_M quantization with 8K context:

Context window matters. An 8B model at 128K context needs ~20 GB KV cache vs ~1.2 GB at 8K - the token limit you set is a hidden VRAM multiplier.

Apple Silicon: unified memory means system RAM is available to the GPU, but Bodega does not treat it all as usable VRAM. The effective budget is min(wired limit, total RAM × (0.75 if RAM ≥ 64 GB, else 0.70)) - read from macOS's own iogpu.wired_limit_mb when available, or that RAM ratio when it isn't. An M4 Pro with 24 GB has roughly 17 GB effective, comfortable for a well-quantized 14B model rather than 32B.

In Code mode (Ctrl+2):

• Click Open Folder in the file tree sidebar (left panel when empty), or use the Editor Welcome screen quick-start button - a native OS folder picker opens
• After selection, the file tree populates, a new code session is created automatically, and the agent gets sandboxed read/write access to that directory

File operations from the AI agent are restricted to the project directory. The agent cannot read or write outside it.

You can also link a folder to an existing session: right-click any session in the Chat sidebar → Link project folder.

Bring your rules with you. When you open a project that contains another editor's rules files, Bodega offers a one-time Import into Bodega toast that appends them to .bodega-rules in the project root.

Sources scanned:

• Imports append under a dated per-source header - your existing .bodega-rules content is never overwritten.
• Re-importing is idempotent per source: anything already imported is skipped.
• Rules take effect on your next message - no restart.
• Declined the toast? The manual path is Settings → General → Profile → Import editor rules, any time.

Text rules only - keybindings and extensions are out of scope. Bodega has no keybinding importer, and shortcuts cannot be rebound yet (Settings → Appearance & Editor → Keyboard shortcuts lists them). The VS Code / Cursor importer on Settings → About brings over editor preferences, not keybindings.

Bodega reads instruction files from the root of the project folder on every message - in the app, the CLI, and external ACP agents alike:

• Every file that exists is used, each under its own --- <file> --- header, in that order.
• They share an 8,000-character budget. A file that doesn't fit is left out whole (never cut mid-file), starting from the bottom of the list, and the backend log says which one.
• Instruction sets attached to the project (see Instruction Sets, below) come next, each under a --- instruction set: <name> --- header, inside the same 8,000-character budget and with the same drop-whole rule. A set can hold up to 32,000 characters, but one longer than 8,000 can never fit, so the set editor warns you when it is.
• Your project's Instructions (Named Projects, below) are added after the files and sets.
• Subfolder AGENTS.md: when a message touches a file (open editor tabs, the selected file, or a path you type), any AGENTS.md in the folders between the project root and that file is added too, outermost first, so the one nearest the file has the final word. Up to 6 files and 6,000 characters; node_modules and .git are skipped, and a file that links outside the project is refused.
• .clinerules, .cursorrules and other editors' files are not read directly - import them into .bodega-rules (see above).
• Edits take effect on your next message. The Context Inspector's Project Rules section shows which root files were loaded, plus any subfolder AGENTS.md that applies to paths named in your last message (it can't see your open tabs, so a real turn may load more).

An instruction set is a named block of rules you write once and reuse across projects, instead of copying the same AGENTS.md into every repo.

Create or import: open Settings → Prompts & Memory → Instruction sets. Click + New set to write one, or Import from file… to load an AGENTS.md, CLAUDE.md, .cursorrules or any other text rules file. An imported set is named after the file (a second AGENTS.md becomes AGENTS (2)), and you can edit it in place afterwards. If you give the import a name yourself (the CLI's --name) and that name is taken, the import is refused instead of renamed. Names ignore case: Team and team count as the same name, so creating or renaming a set to a name that differs only in case from another set is refused. A set holds up to 32,000 characters. Deleting a set asks first and removes it from every project it was attached to.

Attach to a project: in a Named Project's sidebar, open Instruction sets, tick the sets you want, order them with the arrows, and click Save. Sets attach to the project's linked folder, so the project needs a folder path.

What the agent gets: attached sets load after the project's own .bodega-rules, AGENTS.md and CLAUDE.md, in the order you chose, and before the project's Instructions. They share the 8,000-character Project Rules budget with the root files; a set that doesn't fit is left out whole. The Context Inspector's Project Rules section lists the attached sets by name, and any that were dropped.

CLI: the CLI gets attached sets automatically, because the backend loads them from the project path.

Inside a project instruction file (.bodega-rules, AGENTS.md, or CLAUDE.md) you can fence a fragment so it only loads when the turn actually touches matching files:

<!-- bodega:rules paths="app/**,**/*.sql" -->
Never write raw SQL - use the query builder.
All API routes live under app/routes/.
<!-- /bodega:rules -->

A fenced fragment is injected into the agent's context only when the current turn touches a file matching one of its globs - determined from your open editor tabs, the selected file, and any path-like tokens in your message. Everything outside a fence is always injected, exactly as before.

• Globs support * (single segment), ** (any depth), and ? (single char).
• A rules file with no fences behaves identically to how it always has - the whole file is always injected.
• Malformed or unclosed <!-- bodega:rules --> blocks fail open: the text is kept and injected rather than dropped.
• There is no UI for this - edit the rules file directly.

Use it to keep large rule sets relevant: front-end conventions only surface when you're editing front-end files, migration rules only when a .sql file is in play.

A named project groups sessions together and injects custom instructions into every agent call in that project.

Create one: gear icon → Projects → New Project. Fields:

• Name (required)
• Description - for your reference
• Instructions - injected into every agent request in this project (up to 10,000 chars). Use this for coding standards, repo conventions, or context the agent should always have.
• Default model - overrides the global model setting for all sessions in this project
• Folder path - links the project to a directory

Assign a session: right-click a session in the Chat sidebar → Add to project → pick from the list.

Memories saved in a project session are tagged to that project and searched first before global memories. A .bodega/config.json file in the project root can add project routing rules and Run Tasks entries (see Settings, Themes & Spending for what it can and cannot change).

A session is a persistent conversation thread. Sessions persist indefinitely in SQLite.

Create:

• Chat mode: click + in the sidebar header
• Code mode: opening a folder or project auto-creates a new code session

Rename: double-click the session title in the sidebar and press Enter, or right-click → Rename

Archive: right-click → Archive - hides the session from the main list but keeps all messages. View archived sessions at the bottom of the Chat sidebar in the Archived section. Click Restore to un-archive.

Delete: right-click → Delete - shows a confirmation dialog. Also supports multi-select with bulk delete.

Export: right-click a session for four export formats - Markdown, a self-contained web page, a self-hostable viewer bundle, and a redacted bug-report JSON. Full breakdown of what each one contains on the Tips & Tricks page.

Archived sessions are excluded from search results.

Three read-only panels live alongside the editor, each answering a different "what is actually happening" question.

Network - every outbound HTTP call Bodega's backend makes (provider requests, health checks), polled every 3 seconds while the window is visible (polling pauses when minimized or backgrounded). Shows method, URL, status, duration, and size; API keys embedded in a URL are masked before display. Clear empties the panel view only - it does not touch the underlying log.

Output - the backend's own log stream, relayed live over the app's WebSocket connection and capped at 1,000 entries. Filter by level (All / Info / Warn / Error) or search text; Follow keeps the view pinned to the newest line, like tail -f. Currently one channel (Backend); the channel selector is real UI built ahead of additional sources (LSP, llama-server output) landing in it.

Problems - TypeScript/lint diagnostics grouped by file, with error/warning/info severity icons. Click an entry to jump to that line in the editor.

The search bar at the top of the Chat sidebar searches across session titles and message content. Results include a snippet from the matched message.

Behavior:

• 300ms debounce - results update as you type
• Returns up to 20 results, ordered by last active date
• Excludes archived sessions
• Uses SQL LIKE pattern matching, not full-text search with stemming

This means "running" will match "running" but not "run" or "ran". The Knowledge Base uses FTS5 with Porter stemming; session search does not. Clear the field or click the X to return to the full session list.

Sessions have a type that determines what features are available:

Chat sessions (type='chat') - created when you click + in Chat mode. Conversational only. No file tree, no AI panels, no terminal. The agent has no file system access.

Code sessions (type='code') - created when you open a folder in Code mode. Full IDE: file tree, four AI panels (Agent, Research, Debug, Advisor), Monaco editor, terminal. The agent can read and write files within the project sandbox.

Switching modes with Ctrl+1/Ctrl+2 changes the UI but does not change the session type retroactively.

The Git panel in Code mode includes an AI review of your current diff - useful before committing.

Code mode → left sidebar → Source Control icon → Git panel → click Review

What it does:

• Reviews staged + unstaged changes by default (the uncommitted work use case)
• Falls back to branch-vs-base diff if the working tree is clean
• Caps the diff at 14,000 characters before sending to the LLM
• Returns findings grouped under ### Critical, ### High, and ### Suggestions headings, or "No significant issues found." if nothing stands out

The review uses your configured LLM - the same model used for code explanation tasks. A large diff will be truncated; a note appears in the result when this happens. Click Dismiss review to clear the result.

The Bodega Map visualizes your project as an interactive node graph - files as nodes, import relationships as edges. Open it from the activity bar on the left edge of Code mode (grid icon).

Works in both layouts. On Dockview it opens as a panel tab; on the legacy layout engine it opens as an editor tab. No configuration change needed.

What you can do:

• Filter bar - type to highlight matching files
• Hide tests toggle - collapses test/spec files
• Click a node → opens a drawer with imports, exports, and an Explain this module button (cached by content hash - re-running on an unchanged file is instant)
• Click the filename in the drawer to open it in the editor
• Generate Map button - bulk-explains every visible file using Fleet Parallel (4 at a time, skips already-cached files)
• Ask the Map bar - natural language Q&A grounded in your codebase

Nodes with an amber dot have changed since their explanation was last generated (tracked via the staleness endpoint).

The @xyflow library that renders the graph is lazy-loaded and does not affect startup time.

bodega (the CLI, a separate Go binary) has its own first-run flow: bodega init runs onboarding (init --reset clears it, init --analyze drafts a project brief), and bodega doctor diagnoses the local environment - PASS/WARN/FAIL, whether an already-running engine will be reused for this project. Full CLI story on the CLI page.

Bodega One checks for updates a few seconds after launch and every four hours, and downloads a new version in the background. When it is ready, a small prompt appears: Restart to update or Later. Restarting applies the update and reopens the app without an installer wizard. Later means later: closing the app normally does not install it, and the downloaded update is picked up again next launch. If any run is active (including background and Fleet sessions) the prompt says so, flags pending approvals that will expire on restart, and Restart after run waits until the run finishes instead of interrupting it. On the first launch after an update, a one-line notice links to the release notes.

Settings → About shows the version, channel (beta or stable), when it last checked, and a Check for updates button (it becomes Retry after an error). With air-gap mode on, Bodega One makes no update checks at all; install a new build manually. Updates only apply to installed builds, not a development checkout. The bodega CLI is separate: run bodega self-update to check for a new release.