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 → 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.

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

1. Setup wizard - detects any running LLM providers (Ollama, LM Studio, vLLM, llama.cpp) by scanning their default ports in parallel. Shows your hardware tier and recommends a model. Takes about 30 seconds if a provider is already running.
2. Guided tour - an 8-step spotlight tour fires the first time you enter Code mode. Each step highlights a UI area with a description and a Next button. Steps that can't find their target (because a panel isn't open yet) are skipped automatically.
3. Onboarding checklist - a floating card in the bottom-right corner tracks six setup milestones. It checks itself off reactively as you complete each one; no action required.

If you click Skip during the wizard or close the checklist early, you can re-run everything from the hamburger menu.

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

• Take Guided Tour - replays only the 8-step spotlight tour from step 1. The wizard does not re-run.
• Run Setup Again - resets everything: wizard, tour, and the onboarding checklist all fire again from scratch.

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

The floating checklist tracks these milestones. Each one checks itself off automatically when the condition is met:

The checklist is hidden on narrow screens. Dismiss it with the X button (permanent, unless you use Run Setup Again). Collapse it to a pill with the minimize button.

Bodega supports 24 provider presets: 9 local, 14 cloud, and 1 custom OpenAI-compatible endpoint.

Local (no API key needed): Ollama, LM Studio, vLLM, llama.cpp, LocalAI, KoboldCpp, GPT4All, MLX (Apple Silicon), Jan

Cloud (API key required): Anthropic (Claude), OpenAI, Google Gemini, Groq, Azure OpenAI, Together AI, OpenRouter, Mistral AI, Cohere, DeepSeek, Fireworks AI, Qwen (Alibaba DashScope), Kimi (Moonshot AI), Featherless AI

Three ways to configure a provider:

• The setup wizard on first launch - detected providers appear immediately
• Models → Providers tab - click any provider card, enter credentials, click Test Connection, then Set as Active
• Hamburger → Run Setup Again - restarts the wizard

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 - the setup wizard auto-detects Ollama on port 11434.
3. If you're past onboarding: Models → Providers → Ollama card → Set as Active.
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 (no local provider found):

1. Wizard shows "No provider found" → click Set up cloud provider
2. Pick a provider from the cloud list
3. Enter your API key - validation runs automatically against the provider's API
4. On success, the provider is set active

Post-onboarding:

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

Each provider has its own key stored separately (llm.<presetId>_api_key). Setting an OpenAI key does not apply to Anthropic or any other provider.

Air-gap mode hides the cloud setup option entirely. Cloud providers also require an internet connection - they are blocked in air-gap mode.

When llama.cpp is the active preset, Bodega can own and manage the llama-server process directly - spawn, crash recovery, and teardown on close.

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

Post-onboarding: Models → 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. Models → My Models → Embeddings section
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 all system RAM counts as VRAM (minus ~3 GB OS overhead). An M4 Pro with 24 GB handles 32B models comfortably.

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.

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 also override settings.

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 → Export as Markdown - downloads a .md file of the full conversation.

Archived sessions are excluded from search results.

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.