Code Mode & Editor

1. Press Ctrl+2, or click the Code icon in the left activity bar.
2. On first launch, a one-time dialog asks whether to use the Dockview layout (drag-to-split panels) or the Legacy layout (fixed CSS grid). You can change this later at Settings → Layout → Layout Engine.
3. Open a project folder with the Open Folder button in the status bar or top bar. The file tree, git status, and the agent's workspace scope all follow this folder.

Dockview is the default layout engine since beta.22. Every panel - Explorer, Editor, Agent, Terminal, Source Control, Search, Preview, Symbol Outline, Map, Fleet - is an independent pane you can drag, tab, split horizontally or vertically, and resize. Layout is saved automatically (500 ms debounce) to the ui.dockview_layout setting.

Default arrangement: Explorer (left, 220 px) + Editor (center, fills remaining space). The Agent panel opens lazily the first time you use it and docks at 380 px on the right.

Reset: Settings → Layout → Reset Layout (only enabled in Dockview mode).

Always-mounted panels (Terminal, Preview, Agent, Fleet) stay in the DOM when hidden - their processes and state survive panel hide/show cycles. Fleet Monitor is not always-mounted.

If the persisted layout is corrupt or empty, Bodega falls back to buildDefaultDockviewLayout() automatically.

The Legacy engine uses a CSS grid with react-resizable-panels. Panels are fixed regions - no drag-to-split. Switch to it at Settings → Layout → Layout Engine → Legacy, or choose it in the first-launch dialog.

Two things only work in Dockview:

• Reset Layout button is disabled in Legacy mode.
• Bodega Map opens as an editor tab in Legacy mode (not a dockable panel).

The editor uses Monaco (@monaco-editor/react) with the custom accent-dark theme, which reads CSS custom properties on mount and updates automatically when you switch the app theme.

Defaults: Geist Mono, 14 px (Consolas/Courier New as fallback). Syntax highlighting, IntelliSense, bracket matching, minimap, sticky scroll, and smooth cursor animation are all on by default.

Adjust in Settings → Editor: Font Size, Font Family, Tab Size, Word Wrap, Minimap, Render Whitespace (Selection / All / Boundary / None).

All standard Monaco shortcuts work: Ctrl+F (find), Ctrl+H (replace), Ctrl+Shift+P (command palette). Ctrl+G opens the go-to-line dialog (the status bar's Ln:Col is display-only, not clickable). Ctrl+=/Ctrl+-/Ctrl+0 zoom the font in, out, and back to default. Files opened from outside your project folder (see below) load read-only.

• Open: click a file in the Explorer panel, or press Ctrl+P for quick-open.
• Save: Ctrl+S. A dot on the tab means unsaved changes.
• Save As: Ctrl+Shift+S.
• Revert to disk: Ctrl+Shift+R when the editor is focused - re-reads the file from disk. A toast confirms, and Ctrl+Z undoes the revert. (With the editor not focused, Ctrl+Shift+R opens the Research panel instead.)
• Close tab: Ctrl+W. If the file has unsaved changes, a confirmation dialog appears.
• New file / Open file: click the + button in the tab bar.

Open files from outside a project (beta.27): double-click a file in your OS file manager, choose "Open with → Bodega One", or run bodega path/to/file from a shell - it opens in an editor tab without needing a project folder, the same way VS Code opens a loose file. File associations are registered by the installer; on Windows, Bodega appears in the "Open with" list and you choose whether to make it the default. A file opened from outside the currently-open project folder gets a Read-only · outside workspace badge and can't be edited - open the containing folder as a project to edit it.

Large files (5-20MB): a warning asks before opening, from every entry point (Explorer, Quick File Open, go-to-definition, search results). Files over 20MB won't open in the editor.

Tab overflow: when there are more open tabs than fit the tab bar, a … button appears at the right edge listing the hidden tabs.

Split editor: Ctrl+\ toggles a second pane; a small orientation button above the split switches between side-by-side and stacked (vertical).

Keyboard-only tab reordering: focus a tab (Tab key or click) and press Alt+←/Alt+→ to move it left or right - the same reorder dragging does. Menu (or Shift+F10) opens that tab's right-click context menu (pin, close, close others) without a mouse.

After the agent edits a file, Monaco shows colored 3 px bars in the gutter:

Decorations appear after the write completes, not during streaming. While the agent is actively writing, a real-time inline streaming diff overlay replaces them. Decorations clear when you edit the file yourself. Removed lines are not marked - they no longer exist in the file.

1. Toggle blame via the Status Bar (click the git branch name) or dispatch the bodega:toggle-blame window event.
2. Each line shows an inline annotation with the commit author, date, and the first 50 characters of the commit message.
3. To update annotations after a save, toggle blame off and on - it does not auto-refresh.

Requirements: the project folder must be a git repo. Non-git projects show an error.

AI inline completions appear as grey ghost text as you type, similar to GitHub Copilot. Bodega sends the code before and after the cursor to the configured FIM model.

Three modes (Settings → Models → Autocomplete):

• Off - disabled.
• Primary - uses your active chat model with a FIM-capable endpoint.
• Custom - a separate FIM model/provider (URL + model name).

For Ollama, native FIM uses /api/generate with a suffix param. For OpenAI-compatible endpoints, /v1/completions. If the endpoint doesn't support native FIM, a chat-prompt-injection fallback runs instead.

Model resolution order: fim.model → llm.fim_model → auto-detect → llm.code_model → llm.default_model. Ollama's running models are scanned every 60 s to detect FIM-capable options.

1. Select the problematic code in the editor.
2. Right-click → Fix with Bodega (or use the lightbulb that appears on error lines).
3. The floating input pre-fills with "Please fix" - edit it to describe what you want.
4. Press Enter or click Fix. The agent streams the fix directly into the file.

The widget anchors near the selected text via a React portal (rendered to document.body, z-index 200). It hides automatically when a secondary panel like Settings is open.

All four AI context-menu actions require a non-empty selection.

Per-hunk review is one workflow reached from two places - a batch list and a per-file detail view - sharing the same hunk split, the same decisions, and the same keyboard vocabulary (j/k move focus, a/r accept/reject, Ctrl+Enter primary action, Ctrl+Backspace secondary action, Esc close):

Batch list - Hunk Review panel. Click Review Changes in the editor tab bar, press Ctrl+Shift+D, or click the Review hunks button (stacked-blocks icon) next to any file in the Agent panel's change list. Shows every hunk for one file as a card with context and colored diff lines. Accept/Reject per hunk, Accept All/Reject All for the whole diff, Ctrl+Enter applies the accepted hunks to disk, Ctrl+Backspace is Reject All (there's no whole-file revert here - that's the per-file detail view's job). Hunks are applied bottom-to-top to keep line numbers accurate; very large diffs may be slow to compute.

Per-file detail - the editor's own Diff Review tab (opened from the editor tab bar's diff icon, not Ctrl+Shift+D). Whole-file Keep/Undo stay the primary action; each hunk also gets an inline Accept/Reject toggle plus a "N of M hunks kept" summary. Every hunk starts accepted, so Keep with no toggling is identical to the old whole-file Keep.

Moving between them: the batch panel's Open in Diff Review button hands its current per-hunk decisions to that file's Diff Review tab, so refining continues from the same choices instead of starting over - pick whichever view is already open, or start in the batch list and drop into detail for one file.

Bodega saves a snapshot of every file before each tool call that modifies it. Snapshots are stored in the checkpoints SQLite table.

To browse or restore a snapshot:

1. Open the secondary panel (Ctrl+Shift+D).
2. Select the checkpoints tab.
3. Click a snapshot to preview it, then click Restore to roll back.

Checkpoints are per-session and per-file. They are not git commits - they won't appear in git history. They clear when the session ends.

Bodega runs a language server for .ts and .js files - it ships with the app, nothing to install. Errors and warnings appear as red/yellow squiggles in the editor and are counted in the status bar.

• Hover a squiggle for the diagnostic message and quick-fix lightbulb.
• Navigate between errors with F8 (next) / Shift+F8 (previous).
• The Problems panel lists all diagnostics for the project.
• Turn it off in Settings → Editor → AI Features if you prefer Monaco's built-in support.

Other languages get Monaco syntax highlighting but no LSP diagnostics. There may be a brief delay on first file open while the language server initializes.

The Outline panel (Dockview panel ID: outline) shows the active file's symbols - functions, classes, variables. For TypeScript/JavaScript and Python it asks the language server directly (textDocument/documentSymbol) when LSP is on; for every other language, and whenever LSP is off, it falls back to a best-effort scan.

Click any symbol to jump to that line. The panel is in the left column by default, below Explorer. Ctrl+Shift+O opens the same symbol list as a quick-jump overlay without leaving the editor - type any part of a symbol's name (fuzzy matching, same as Ctrl+P) and each result shows a muted kind marker (F = function, C = class, and so on).

The breadcrumb bar above the editor also shows the enclosing function or class at the cursor's current line, sourced from the same symbol data - e.g. file.ts › handleSubmit.

The status bar runs along the bottom of Code Mode.

Left side (all clickable):

Right side:

The permission mode chip (Ask / Plan / Act) lives in the Agent panel's composer row, not the status bar - see "Agent panel" below.

Custom agent identity (beta.27). When a custom agent is selected in the Agent panel, the status bar's model entry switches to the agent's name and pinned model (Reviewer · qwen3:8b) with the agent icon in the accent color - so it is always visible that the default agent is NOT the one running. Pick Default in the agent dropdown to return to the normal model display.

The Agent panel (Dockview ID: panelSidebar) is the primary AI interaction surface in Code Mode. It has four sub-panels, each with its own tool allowlist and per-panel iteration limits:

Open with Ctrl+Shift+D or click the Agent tab in the Dockview layout. Type a prompt in the composer and press Enter or Send. Use @ to attach context (files, symbols). The composer row is + (attachments) · the permission chip (Ask ▾) · Thinking · the context ring · the model chip; there is no Web toggle here - the agent's web search and fetch tools are available whenever tools are, so ask it to search. The action row under the composer also carries a Run tasks chip (beta.28) - the same one-click dev-server launcher as the play button in the terminal tab bar.

The panel is always-mounted - it stays in the DOM when hidden. Per-type empty states explain each sub-panel when no session is active.

The Run in Background button (clock icon, next to Send) lets you fire off a task and walk away. The agent keeps working; you get a toast and OS notification when it finishes or needs approval.

1. Type your prompt in the Agent composer.
2. Click the clock icon. Optionally check Isolated to run in a throwaway git worktree - recommended for multi-file or risky tasks.
3. The composer clears immediately. A toast confirms the background run started.
4. Monitor progress via the Fleet indicator badge in the top bar.

When the button is hidden: it only appears when a real session exists (sessionId is non-null) and a project folder is set. Isolated mode requires a git repo - the backend returns a clear error if the project isn't one.

All in Settings → Agent:

How the loop runs: each message enters a multi-iteration cycle. The agent calls tools, checks results, and decides whether to continue or respond. Tool results are capped at 16,384 characters. Context compacts proactively at an iteration boundary once the window is llm.auto_compact_threshold percent full (default 75), with a hardcoded emergency compaction at 85% behind it. Set the threshold to 0 to leave only the emergency backstop.

When compaction runs, the status line under the composer shows "Compacting conversation history..." while it summarizes older turns, then "Context compacted - continuing..." once it's back to work. If the summarization call itself fails, the agent silently falls back to trimming the history mechanically instead - you won't see the second status line in that case, but nothing is lost from the current turn.

Open via the Activity Bar or by clicking the branch name in the status bar.

Staging and committing:

1. Click + next to a file to stage it.
2. Write a commit message, or click Generate for an AI-generated one (POST /git/suggest-commit, uses your active explain model).
3. Click Commit.

Branches: use the branch dropdown at the top of the panel to switch or create branches.

Diffs: click any file entry to open a split-right diff view.

PR description: click Generate PR Description to get a structured markdown summary based on your commits ahead of main (falls back to master).

Git status polls every 5 seconds, but only while the Source Control panel is open.

Hunk-level staging (beta.27). Open a file's diff in the panel and each hunk gets its own Stage hunk / Unstage hunk button - stage exactly the lines you mean to commit without staging the whole file. (Untracked files stage whole-file - there is no hunk boundary in a brand-new file.) Failures surface in the commit error strip, never silently.

Conventional commit types (beta.27). A small type picker sits next to the commit message - pick feat/fix/chore/docs/refactor/test/perf/style and it prefixes the message (replacing any existing type, never stacking). Use Generate for the body and the picker for the type - zero extra model calls.

When a session completes a QEL-verified run, Bodega can append a signed Bodega-QEL trailer to the commit message - capturing that run's contract, score, pass/fail, and model, plus an HMAC Sig keyed to a local machine secret.

The QEL Proof bar at the bottom of the Source Control panel has a Verify history button that walks recent commits and re-checks each trailer's signature against the local secret, reporting per commit:

• ✓ verified - the trailer is intact and the signature matches.
• ✗ tampered - a trailer is present but its signature no longer matches (the message or proof was altered).
• • unsigned - the commit carries no proof trailer.

Building and verifying the proof are fully local (POST /git/proof-trailer, POST /git/verify-history) - no network, so it works in air-gap mode. The signing secret never leaves the machine, which means trailers verify only on the machine that produced them.

Ordinary agent commits are attributed too. Commits the agent makes without a QEL run behind them (auto-commits, automation worktree commits) carry a plain two-line footer - Bodega-Agent: <model> and Bodega-Agent-Proof: none - so an agent-authored commit is never mistaken for a human one, and the absence of verification is stated rather than implied. This footer is unsigned and deliberately cannot be confused with the signed Bodega-QEL trailer. It is on by default; turn it off with the git.agent_attribution setting.

The magnifier icon in the activity bar opens project-wide search. Type two or more characters and results stream in grouped by file; click a result to open the file at that line.

Toggles: match case (Alt+C), regex (Alt+R), whole word (Alt+W), plus include/exclude glob filters and context lines. Search & replace works per-file or across all results.

Recent searches (beta.27): the clock icon in the search box lists your last 10 queries - click one to re-run it. History survives restarts.

Honest failures (beta.27): an invalid regex, a missing desktop bridge, or an internal search error now shows an error card explaining what happened - a failed search no longer masquerades as "No results found".

The Review button in the Source Control panel runs an AI review of the current git diff.

1. Open the Source Control panel.
2. Stage or modify files (or work on a branch with commits ahead of main).
3. Click Review.

The backend (POST /git/review-changes) checks for uncommitted changes first - staged and unstaged. If the working tree is clean, it reviews the branch diff versus main/master. The diff is capped at 14,000 characters (truncated with a suffix if exceeded).

Review output groups findings under ### Critical, ### High, and ### Suggestions. Empty sections are omitted. If nothing stands out, you get "No significant issues found."

Clicking Review again replaces the previous result. Requires a git repo and an active LLM provider.

Delta-only re-review (beta.28): files unchanged since your last review of this project are skipped, and the result says how many ("3 files unchanged since last review - skipped") with a Review everything link when you want the full pass. Review → fix → review loops stop re-paying for the whole diff.

The Map panel (Dockview ID: codeMap) is an interactive file dependency graph powered by @xyflow. Nodes represent files; edges represent imports and dependencies. CodebaseGraphScanner builds the graph by merging JS/TS imports, HTML/CSS cross-links, and structural edges.

Interacting with the graph:

• Click a node to open a detail panel showing the file's module summary.
• Click Explain on a node to get an AI-generated summary from GET /codebase/wiki/explain (cached in the wiki_summaries SQLite table).
• Amber dots on nodes mean the AI summary may be stale - the file's content hash changed since the last explanation.
• Zoom with the scroll wheel or the zoom controls. The minimap (bottom-right) gives an overview.

@xyflow is lazy-loaded to keep it out of the main bundle. In Legacy layout mode, the Map opens as an editor tab instead of a dockable panel.

The Terminal panel (Dockview ID: terminal) is a full xterm.js terminal running in your project folder. It is always-mounted - the shell process persists when the panel is hidden.

Click + in the terminal panel for a new terminal instance. Manual terminal commands have no agent security filter; only the agent's ShellTool has the credential-scanning and sandbox restrictions.

The Preview panel (Dockview ID: preview) is an embedded browser for your own project - localhost addresses only. Open it with /preview (bare /preview shows a port picker for 3000 / 5173 / 8080 / 4200), or let the agent open it via open_preview. Pasting a non-localhost URL shows an explicit "Invalid URL" card telling you only localhost is allowed and pointing you at the Agent Browser (globe icon in the activity bar) for external sites - nothing is rejected silently.

Device frames. The toolbar has a device picker: Responsive (the default - no emulation, the page just fills the panel) plus five presets - iPhone 16 Pro, iPhone SE, iPad Pro 11", Pixel 9, and Galaxy S24. Picking one renders the page at that device's real CSS viewport, pixel density, and user agent, inside a drawn phone/tablet frame, with emulated safe-area insets. A rotate button (visible only while a device is selected) flips portrait ↔ landscape. Pick Responsive to go back to normal.

Be clear about what this is: Chromium at the selected device's dimensions - layout-accurate, but not Safari and not a real device. WebKit-only behavior (rubber-band scrolling, input auto-zoom, Safari bugs) is out of reach by construction, and the safe-area insets are emulated values, not the real env(safe-area-inset-*). The picker's tooltip says the same thing.

Console errors in the panel. Page errors and warnings show up in a small strip at the bottom of the Preview with counts - click it to expand the recent entries (errors and warnings only; plain log output stays in DevTools), and clear them from there. When the page is clean the strip isn't shown at all.

Starting and reconnecting. If no dev server is detected, the empty state can start one for you: one click runs your project's dev script (top-ranked from your package scripts) in a Terminal tab, and the preview connects when the server prints its URL. There's also a Preview this folder button that serves a static index.html locally for no-build-step projects. And if your dev server dies while the preview is open, the "Dev server not running" card keeps probing the port and the preview reconnects by itself the moment it answers - you don't have to click Retry.

Bodega can own the llama-server --embedding process for local Knowledge Base / RAG embeddings, running on port 8081 (separate from the chat server on 8080).

To configure:

1. Go to Settings → Models → Codebase Embeddings.
2. Set the provider to llama.cpp and check Let Bodega manage the embedding server.
3. If GGUFs are already installed (downloaded via Models → llama.cpp → Discover), pick one from the dropdown. Otherwise, type the full path to a GGUF in the manual path field.
4. Set the port if needed (default 8081).
5. Click Save. The server starts automatically on the next embedding operation.

Requirements: the llama.cpp binary must be installed (Settings → Models → llama.cpp → Install). Recommended embedding models: nomic-embed-text, bge.

The managed server fixes context at 8192 tokens, binds to loopback only, and does not use flash attention (some builds reject it in embedding mode). Concurrent start requests coalesce onto a single start promise. It starts lazily, on the first batch of embeddings - not when you save the setting.

It is deliberately simpler than the chat server: no crash-recovery loop. If it dies mid-index, it stays dead until the next start; it is not restarted for you the way the chat server is.

Relevant keys: embeddings.llamacpp_managed, embeddings.llamacpp_port (8081), embeddings.llamacpp_model_path.

The Fleet panel (Dockview ID: fleet) shows active parallel agent runs - multiple agent sessions working concurrently on the same task. Each session's insertions/deletions, status, and winner selection are visible here. Use Accept / Discard to apply or drop a session's changes.

The Fleet Monitor panel (ID: fleetMonitor) shows an aggregate run status table. Unlike other always-mounted panels, Fleet Monitor is not always-mounted - its 5-second poll pauses when the panel is hidden.

Status streams via GET /api/parallel-runs/:runId/status-stream (a dedicated SSE endpoint, not the main chat-stream). The Fleet TopBar badge shows counts of running and awaiting-approval sessions.