AI Panels & the Agentic Loop

Permission modes (Act / Ask / Plan) apply only to the Agent panel. Research, Debug, and Advisor are always read-only regardless of the mode shown in the header.

Each panel can run a different LLM. To assign models:

1. Go to Settings → Models → My Models.
2. Set the Agent, Research, Debug, and Advisor roles to whichever models you want.
3. Leave a role blank to fall back to the Agent (code) model - the panel header shows a ↩ indicator when it's using the fallback.

The panel header displays a cleaned-up model name. Managed and side-loaded GGUF models show a name derived from their filename (SmolLM2-1.7B-Instruct-Q4_K_M.gguf renders as SmolLM2 1.7B Instruct) rather than their internal ID or the file's path on disk.

Settings keys:

• Agent → llm.code_model
• Research → llm.research_model
• Debug → llm.debug_model
• Advisor → llm.advisor_model

The Agent panel is where actual coding happens. It has access to all 36 statically registered tools plus any MCP tools you've connected, runs QEL (Quality Enforcement Layer) verification in full mode, and supports permission gating so you can review writes before they land.

What you'll see while it runs:

• Tool call cards - every tool invocation appears as an expandable card showing tool name, status, args, result summary, and duration in milliseconds.
• FileChangeCards - file writes show filename, status badge (New / Modified / Error), line delta (+N / -M), and buttons to open the file or view a diff.
• ThinkingIndicator - shows the current status (Preparing…, Reading files…, etc.) and iteration number.
• TodoPanel - appears when the agent uses todo_write to self-plan a multi-step task.
• Queued messages - messages typed while the agent is running are queued and injected between iterations. The queue appears at the bottom of the panel with cancel buttons per message.
• Small-model warning - a banner appears when the active model is below 13B parameters.

The iteration budget. Your agent.max_iterations setting (Settings → Agent, default 50) is the starting budget. A run that keeps making progress is extended in steps of 10 iterations and 25% more time, up to four times, toward the absolute ceilings agent.max_iterations_ceiling (default 200) and agent.loop_duration_ceiling_ms (0 = 120 minutes local, 60 minutes cloud). At the ceiling you get an 'extend the run?' card. A run that makes no progress across the stagnation window is stopped early and says so. Underneath it the budget is computed per run: a model profile's own recommendation can tighten it but never raise it above your setting, MoE models get a 30% bump, creation tasks get one extra iteration per two deliverables (max +5), complex commands add 25%, and research mode doubles the base. Models without native function calling are capped tighter still.

One case only ever raises the floor: a goal-driven run (/decompose, an adopted plan) asks for roughly three iterations per goal task plus overhead, so a five-task objective isn't strangled by a low model recommendation. It is still clamped to your setting.

The colored dot in the PanelSidebar header shows the current mode. Change it with the pill selector at the bottom of the Agent panel input.

Act (green dot) - every tool runs automatically. No approval prompts.

Ask (yellow dot) - file writes and shell commands pause for approval before running. Reads and searches proceed automatically. A card appears with Accept / Reject buttons; Enter accepts, Esc rejects. Disconnecting does not auto-reject a pending tool approval for a real session - it stays open with its auto-decision timer cancelled, and you decide on reconnect. Only an anonymous session with no way to reattach still auto-rejects on disconnect.

Plan (purple dot) - the agent generates a plan first and stops. The PlanApprovalCard slides up from the bottom showing the proposed files with CREATE / MODIFY / DELETE / READ badges. Enter approves the whole plan and execution starts; Esc rejects. If the model fails to produce a valid plan after 3 attempts, the run stops without executing any tools and tells you to rephrase, switch modes, or try a different model. It never falls back to running things unapproved - Plan mode requires an approved plan before any tool runs, and there is no path around that. Plan approvals persist to the database and survive disconnects - the pending plan is restored when you reload the session.

The /mode slash command also toggles modes. Mode is saved per session.

The code mode is a legacy alias for Ask behavior - if you see it, it behaves identically to Ask.

1. Press Ctrl+L to focus the Agent panel.
2. Type a task and press Enter. The agent starts streaming immediately.
3. To attach context, click + Current File or + Selection above the input to attach the active editor file or your highlighted selection.
4. To capture a screenshot, click the camera icon.
5. To queue a follow-up while the agent is running, type in the input and click the queue-send button (separate from the main Send).
6. To stop, click the Stop button. This also clears the message queue.
7. Approval prompts (Ask / Plan mode) pause execution - use Accept / Reject buttons or Enter / Esc.

The Research panel runs a read-only agent with web access. It tracks citations and adds source attribution to its responses. It runs for up to 3 iterations.

In air-gap mode (Settings → General → Air-Gap), web_search and web_fetch are removed from the tool list. The panel relabels itself Codebase Research and only has access to query_knowledge and query_memory.

Pin to knowledge - after the agent responds, click Pin in the sub-header to save the response permanently to the knowledge base. The Agent panel will see it on subsequent messages.

Implement → Agent - click this button in the sub-header to hand off the research findings to the Agent panel. The panel switches automatically. The agent picks up the handoff context when you send your next message - clicking the button alone doesn't inject anything yet.

The Debug panel detects stack traces you paste into the input and shows a structured error badge in the sub-header with the error type and file/line location. Detection is client-side and pattern-matched against JavaScript (at function (file:line)), Python (File ... line N), and generic Error / Exception / panic / FATAL signatures.

The panel runs up to 5 iterations and has read access to the file system, grep, glob, code_search, and shell for running diagnostic commands (checking logs, process state, etc.). Destructive shell commands are still blocked.

Fix it → Agent - after diagnosis, click this button to hand off the diagnosis and error context to the Agent panel. The Agent panel picks it up on your next message.

The Advisor panel runs with an Architecture Advisor persona injected into its system prompt. It analyzes code structure, reviews design decisions, and flags patterns and anti-patterns. It can read your codebase via file_system, grep, and code_search, but cannot write files and cannot do live web research (no web_search or web_fetch).

The Decisions toggle in the sub-header opens the DecisionLog viewer - a scrollable history of past advisor responses stored per session.

The sub-header badge reads 15 iter, which matches the backend limit in PanelConfigs.ts.

Panels are designed to chain together. Handoffs move context from Research or Debug into the Agent panel.

Research → Agent:

1. Ask your research question in the Research panel.
2. After the response, click Implement → Agent in the sub-header.
3. The panel switches to Agent. Type your implementation task - the research findings are injected automatically into that message's context.

Debug → Agent:

1. Paste the stack trace and get a diagnosis.
2. Click Fix it → Agent in the sub-header.
3. Type the fix task in the Agent panel - the debug context is injected.

Handoffs are tracked in the Context Inspector as breadcrumbs with consumed / pending status. A handoff is consumed exactly once - the Agent sees it on the first message after the handoff, then it's gone.

The Advisor → Agent path has no formal handoff button. Ask the advisor for a design decision, then describe the implementation task in the Agent panel yourself.

Every message sent to any panel runs through the same pipeline server-side. Entry point: POST /api/chat/complete → AgenticChatService.processMessageStream(). The frontend receives results over an SSE stream.

Stage 1 - Contract extraction (<5ms, no LLM call): parses your message into a machine-checkable contract - what files should exist, what patterns, what language/framework. Confidence can be low, medium, or high.

Stage 2 - Context assembly: assembles system prompt + dynamic context (memory, project rules, repo map, conversation history) within the token budget. Compaction triggers automatically at 70% of the conversation budget (80% for MoE models, which tolerate denser context) - ConversationCompactor.maybeCompact's own threshold gate. This is separate from the user-configurable llm.auto_compact_threshold (default 75%, plus a hardcoded 85% emergency backstop) described on the Code Mode page's "Agent loop settings" - two independent compaction checks exist in the pipeline.

Stage 3 - RuntimeLayer.classify(): determines the execution lane, iteration cap, tool allowlist, and QEL mode from the panel config and message classification.

Stage 4 - Main loop (up to maxIterations): LLM call → parse tool calls → execute tools → inject results → continue or exit. Each iteration emits tool call cards to the frontend.

Stage 5 - QEL verification: three levels (see the QEL section below).

Stage 6 - Post-loop: save messages, emit telemetry, consolidate learnings.

You can stop the loop at any time with the Stop button.

On creation tasks where the contract confidence is low and the system detects two or more information gaps (missing language, framework, target files, underspecified functionality), the loop pauses before the first LLM call and shows a ClarificationCard with 2–3 targeted questions.

Click Submit to answer and refine the contract - this typically upgrades confidence to medium or high. Click Skip to proceed with the original low-confidence contract.

Clarification fires only in the Agent panel, only on creation tasks, and only before the first iteration - it does not interrupt a loop already in progress.

QEL runs automatically on every file write in the Agent panel. You don't configure it - you see its output in iteration cards and the VerificationReportCard that appears in the chat feed for creation tasks.

Level 0 - Pre-execution gates (every write): 9-gate pipeline that runs before a file write hits disk. Includes a permission mode firewall, contract guard (filename must match a declared deliverable), forbidden path check (node_modules, .env, .git), duplicate detection, shell redirect scan, and a fast TypeScript syntax validation via the compiler API (~2ms) that blocks broken JS/TS before it's written.

Level 1 - Mid-loop incremental verification (per file write): scores the written file against the contract (patterns 60% + framework consistency 25% + content completeness 15%). The score needed to avoid a repair nudge is not a flat number - it scales with the active model's size class (QELThresholdScaler.ts): 45 (tiny), 55 (small), 65 (medium), 70 (large), 75 (xlarge). Smaller models are held to a looser bar so they aren't stuck in endless repair loops for output a bigger model would pass on the first try.

Level 2 - Micro-proof gates (every 2nd write): runs the language toolchain:

• TypeScript: npx tsc --noEmit --skipLibCheck
• Python: python -m compileall
• Go: go vet ./...
• Rust: cargo check
• Java: javac
• C#: dotnet build

If the toolchain isn't installed, the failure is recognised as an environment problem rather than broken code: no penalty is applied, but the proof band doesn't earn full marks either - it is capped at a "we could not verify this" score. A genuine compile or test failure does cost you the band outright.

Level 3 - Post-loop full verification: 0–100 score. The pass threshold also scales by model size class, same as Level 1: 55 (tiny), 65 (small), 75 (medium), 80 (large), 85 (xlarge) - 80 is the "large"-tier number, not a universal one. Scoring: file existence (5pts), patterns (35pts), structural integrity multiplier, framework consistency (15pts), completeness (15pts), proof gates (30pts).

Repair flow: up to 3 repair nudges targeting specific missing files and patterns. You see Repairing... in the iteration progress. After 3 failed repairs, the loop ends with a detailed failure report.

QEL mode by panel: Agent = full. Debug = structural (stub detection only, no proof gates). Research and Advisor = none.

The authoritative list is the registration block in backend/src/server-agent-init.ts. Some are gated off by default (consult_mixture, spawn_agent) or only offered in certain contexts, so the agent will not always see all 36.

File tools

Knowledge and session tools

Planning and utility

Browser, vision and docs

Plus dynamic MCP tools via connected MCP servers.

Tool alias correction: the agent automatically maps 62 known alias names to the real tool before a call fails. For example, read_file → file_system, bash → shell, browse → web_fetch, terminal → shell. Common shell binary names (npm, git, python, node, pip, yarn, pnpm) also route to shell. You'll see the correction in the tool call card.

In air-gap mode, web_search and web_fetch are removed from the tool list before the LLM call - the model never sees them.

The Context Inspector shows exactly what context is being sent to the LLM.

In Code Mode: click the (i) button in the PanelSidebar header. The inspector slides up from the bottom of the panel.

In Chat Mode: click the context budget ring/bar in the chat input area.

What it shows:

• Hero ring - a 56px ring with the percent inside, tokens used / context window total, and remaining tokens. Ring color: accent (<60%), yellow (60–95%), red (95%+).
• Breakdown meter - a thin stacked bar under the ring for System, Memory, Conversation, Tools and Other, with a dot-legend showing each section's share of the window. Only the conversation segment carries the accent color; everything else is tonal grey.
• Section list - expandable rows for each context segment, each showing its token count and share of the context window (rows with 0 tokens show " - " instead of a share). The Repo Map section loads on demand.
• Handoff breadcrumbs - cross-panel handoffs with consumed / pending status.
• Compact button - available when the session has more than 2,000 tokens used; reads "Compact now" once usage passes 80%. A "Last compacted" stamp under the ring shows when this client last ran a compaction on the session, or "never".
• Memory remove buttons - trash icon on each memory row to delete that entry from the memory store.
• Repo Map re-scan - triggers a fresh PageRank-based symbol ranking.
• Keyboard - Escape closes the panel; Up/Down arrows move focus between section rows, Enter/Space toggles the focused row.

The inspector polls every 2 seconds during active streaming to show live context changes.

When deferred tool loading is active (agent.deferred_tools), the Tools section lists only the core set the model actually receives natively - the rest stay reachable through discover_tools and are not part of the prompt, so they are not counted here.

Note: in Code Mode, the inspector always shows the Agent panel's session context. The Research, Debug, and Advisor panels don't have their own inspector views.

The Agent panel has a Run in Background button that detaches the session so it runs without holding the UI. You can navigate away - or close the panel - and the agent continues server-side.

When a background session reaches a terminal state (ready-to-apply, error, or awaiting-approval), a badge appears on the FleetTopBarIndicator in the top bar and you receive a toast and OS notification.

This is separate from the Agent panel's normal in-UI streaming - background sessions communicate via the /ws WebSocket channel, not the chat-stream SSE.

Sidechat is a separate conversation surface, not one of the four AI panels above. It sits alongside your Code Mode session, sees the main session's context read-only, and can never modify the main thread or write files itself.

Opening it: click the Sidechat icon in the top bar (Code Mode only), or run the /sidechat slash command. It docks beside the main chat by default; use the dock toggle in its header to pop it out into its own floating window instead.

What it's for: asking a side question about the current conversation or project without derailing the main thread - get an opinion, sanity-check an approach, or explore a tangent - then optionally bring the answer back.

Model: Sidechat runs its own model, configured via the llm.sidechat_model setting (falls back to sidechat.default_mode, which defaults to sharing the main session's active model). There's no per-message model picker in the panel itself. In air-gap mode, a sidechat set to cloud mode shows a warning and the composer is disabled - cloud dispatch is blocked.

Context capture: when you open or resync a sidechat, it snapshots the main session's conversation up to that point. The context badge shows how many main-session turns were included and warns you if the main session's model has changed since that snapshot. Click Resync to re-capture.

Bringing a result back - @-inject: on any sidechat reply, click Inject. A preview shows the exact block (labeled with its provenance) that will be added. Confirm and it's staged to ride your next message in the main session only - it does not persist beyond that one turn.