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 → Appearance & Editor → 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, Runs, 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 → Appearance & Editor → 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 → Appearance & Editor → 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 → Appearance & Editor → 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.

If a file changes on disk after the agent read it, for example because you saved it in the editor while the agent was working, the agent cannot overwrite the whole file from its old copy. The write is refused and the agent is told to read the file again first, so your change is kept.

• Small in-place edits (replacing a block of text) still go through, because they already fail if the text they target has changed.
• Files the agent has never read are not affected.
• If the file was deleted after the agent read it, the first write is refused with a note saying so; writing it again creates it.
• It is on by default. Turn it off with the edit.stale_read_guard setting. The CLI uses the same engine, so it gets this too.

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 & Providers → Models → My models → Where suggestions come from; the on/off switch is Suggest code as you type on the same card):

• 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 → auto-detect → llm.code_model → llm.default_model. llm.fim_model is the older name of fim.model: reading or writing it (for example with bodega config) reads or writes fim.model, and a value saved under the old name moves to fim.model once on upgrade. 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 "Fix this" - 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 your choices once every hunk is decided, Ctrl+Backspace is Reject All (there's no whole-file revert here - that's the per-file detail view's job). Hunks start undecided, and a hunk's whole span of original lines (including unchanged lines between two nearby edits) is replaced by its new lines or left alone, so a mix of accepted and rejected hunks never loses or duplicates a line; 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 all/Undo all stay the primary action; each hunk also gets an inline Accept/Reject control and an "N of M decided" summary. Every hunk starts undecided; a chosen button shows a check or cross and the word Accepted/Rejected, and clicking it again clears the choice. When you decide the last hunk, your choices apply on their own: accepted hunks stay, rejected hunks are reverted, and the review closes. Keep all and Undo all act on every hunk at once. Close leaves the file exactly as the agent wrote it, with nothing decided. With several files waiting, deciding one moves on to the next. If you edited the file after the agent wrote it, Bodega won't overwrite your edit: you can reload the review, overwrite anyway, or cancel.

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.

Each time the agent writes or edits a file with file_system or str_replace, Bodega saves the file's previous content as a checkpoint in the checkpoints SQLite table. Changes made through shell (scripts, formatters, package managers) are not snapshotted, and neither are files over 2 MB. Each chat keeps its newest 50 checkpoints. Restoring a file the agent created does not delete it.

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 → Appearance & Editor → 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 activity bar on the left edge has four panels: Explorer, Search, Source Control and Runs (the tray icon). Runs is where everything that needs you, is working, or finished is listed (see the Runs page). Its icon carries one badge: how many runs need you. Ctrl+Shift+U shows or hides it.

The Fleet, Fleet Monitor and Loops icons are no longer in the activity bar. Their panels are still there: a lane's row in Runs has Open in Fleet, a loop's has Open in Loops, and Ctrl+Shift+F still toggles Fleet.

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 controls are one line at every width: + (attachments) · the permission chip (Ask ▾) · ⋯ More options · the model chip · Mic · Send with a ▾ caret. ⋯ is always there and holds Memory, Harness (only when an external harness is installed), Boost and Fast; each row shows its current value and opens the same control. Memory is always listed; before the chat has its first message it is greyed out and says Memory applies after the first message. Effort lives in the model chip: open it and the first section is Effort (a slider over the model's own levels, an on/off Thinking switch for local models, or a note for models that reason on their own), with a ? that explains it and a line saying what more effort costs (usage for a cloud provider, slower replies for a local model, and only that replies take longer for a custom endpoint). The chip shows the effort you picked as · High; below about 480px that becomes a dot and the model shows its short name, for example Opus 5.5. The model never wraps and Send never moves. The ring around Send (and around Stop while the agent runs) shows how much of the context window is used: yellow past 80%, red past 95%. The context inspector is the Context · Inspect row at the bottom of the model chip's menu. Research, Debug and Advisor use the same composer. 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 row that used to sit above the composer (Run tasks, Run in background, isolated, Run in parallel) is gone: those now live in the ▾ menu (see Send as… below).

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 ▾ beside Send opens Send as… (Alt+R from anywhere in the composer). It is where the ways a message can run live, so the row above the box is just the message's own controls.

A row that cannot run says why instead of just being greyed out: for example Open a project folder to start runs in the background, in parallel or as a loop. While the agent is working the caret is replaced by Stop (and Queue, if you are adding a follow-up), because there is nothing to choose.

After something starts, a polite line under the composer reports it (for example Started in background · Open in Runs). It never appears as a toast. The Runs header also has New ▾ with Background run…, Parallel run… and Loop… for starting any of them without the composer.

When the agent wants to do something that needs your say-so, the call waits in the chat with Allow and Reject buttons. The header names the action as a question (Edit src/math.ts?, Run tests?) so it never reads as if it already happened.

Every card says what will happen, whatever the tool:

A card that Bodega rates High risk (or a destructive action such as a delete) gets a red border and a badge, whatever the tool.

Reconnecting. If you reload or reconnect while a call is waiting, the arguments Bodega replays have had secrets removed and very long values cut short. The card still appears, binds to the right call, and says so: these arguments were cut short / edited to remove a secret before reaching this window. Allow only if you recognise the request.

The Run in Background button (clock icon, next to Send) lets you fire off a task and walk away. The agent keeps working; the run appears in Runs (under Working, then Needs you or Done), and you get an OS notification when it finishes or needs approval if you enabled them.

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. Watch it in Runs (the tray icon in the activity 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 → Behavior:

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 → Prompts & Memory → Knowledge base → Advanced → Embeddings → Codebase index.
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 & Providers → Models → My models tab → llama.cpp models). 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 Runs badge shows how many runs, Fleet lanes included, need you.

bodega run "<task>" --cwd <dir> (or the REPL with --cwd) is the CLI's Code Mode equivalent - the same agentic loop, tool set, and QEL verification, driven from a terminal instead of the editor UI. review / /review mirrors the Local Code Review feature. There's no CLI Monaco editor, file explorer, or Bodega Map - those are app-only surfaces; the CLI reads/writes files as tool calls and reports diffs as text.

Above the conversation there is a one-line plan strip whenever the agent is working from a goal or a to-do list: Step 3 of 6: run tests, a small progress bar and 3/6. Click it to see every step with its state written out (pending, in progress, done, skipped). The steps are saved with the goal, so when a run ends with work left, the unfinished steps are still there, still pending, and the next message picks up where it stopped. When every step is closed it reads All 6 steps done (Step done for a one-step plan), or All 6 steps finished, 1 skipped (Step skipped) when the agent skipped any, until your next message. A skipped step is shown as skipped and is never counted as done, though the bar and count treat it as closed. A to-do list the agent keeps without a goal is shown while it runs but is not saved.

When a turn ends and you were not looking (the window was in the background, or you were in another session) or it stopped needing you (an approval, a question, a diff to review), the conversation ends with a Recap card: what changed (files and lines), what the agent did, whether the result was checked, what needs you, and any plan items still open. It is written from what the agent actually did (its tool calls and the verification result), not from what it said it did. The Verified line reads Not verified when the turn changed nothing to check (it is never shown as Failed), and a muted Answer check line appears only when an answer cited sources the agent never read. A turn you watched to the end has no recap. A follow-up you already sent, started or added to the plan is not offered again. If the card says Approve shell, its Approve button is the same decision as the approval card: whichever you press first counts and the other disappears.

Under the recap, Follow-ups lists up to five things left to do. Here adds it to this session (queued if the agent is still working, otherwise sent as your next message). Background starts it as its own session in its own copy of the project (a worktree) so it cannot disturb this one; it appears under this session in Runs. It stops at its first approval and shows there as needing you; re-run the item in the foreground (Here) to approve it. Later adds it to the plan. The recap is written without a model; an optional rewrite in plainer sentences exists (recap.polish, off by default) and is never used when air-gap is on or the model runs on this computer. Both switches are in Settings → Automations → Background runs → Recaps and follow-ups; the rewrite switch is greyed out, with the reason beside it, while air-gap is on or your active provider is not a cloud provider (Settings uses the cloud-provider list, which is stricter than the backend's check for a model on this computer).