Ask, Agent & Plan Modes

Three modes, pickable via the mode pill at the bottom of the chat panel. They share providers, chat history, project rules, and cost tracking; they differ in what happens after the message hits the extension. Ask is the default.

Side-by-side

	Ask mode	Agent mode
Purpose	Conversational Q&A	Autonomous task execution
Side effects	None — read-only	Reads/writes files, runs commands, browses
Tools	None (pure LLM)	~30 built-in + MCP
Subagents	Not available	8 specialists + general-purpose
Engine	Direct provider streaming	deepagents pipeline (LangGraph)
Memory	Chat history only (session)	Chat history + persistent core memories
Cost	Lower (one LLM call per turn)	Higher (multi-step reasoning + tool calls)
Latency	Faster	Varies — simple tasks fast, complex tasks longer
Context enhancement	RAG (vector DB + files)	RAG + tool-based code retrieval

Ask mode

Read-only. Cannot modify files, run commands, or reach external services.

graph TB A[User message] --> B[Context enhancement<br/>vector DB + active file + @-mentions] B --> C[Provider LLM<br/>streaming] C --> D[Streamed response]

Flow:

1. ContextEnhancementService enriches the message with vector-DB results, active file, and any @-mentioned files.
2. Sent directly to the configured LLM provider.
3. Response streams back token by token.
4. Persisted to session chat history.

When to reach for it: quick questions, code snippets, error explanations, code-review feedback without applying, learning/exploration.

Chat-history compaction runs the same 5-tier strategy as agent mode (see Self-healing L4) — token budget from codebuddy.contextWindow.

Agent mode

Full deepagents pipeline — LangGraph agent loop, tool use, subagent delegation, autonomous execution.

graph TB A[User message] --> B[CodeBuddyAgentService<br/>session + safety guard + cost] B --> C[Developer Agent<br/>createDeepAgent] C --> D[Tool calls<br/>file ops · terminal · search · debug · browser] C --> E[Subagent delegation<br/>task tool] C --> F[Memory + docs store] C --> G[MCP tools] D --> H[Streamed response + applied changes] E --> H F --> H G --> H

Flow:

1. Message wrapped with session metadata → CodeBuddyAgentService.
2. Service constructs/reuses the DeveloperAgent (createDeepAgent() from deepagents) with the full middleware stack.
3. deepagents runs the agent loop: reasoning → tool calls → subagent delegation → planning (via built-in todoList, filesystem, subAgent middleware).
4. Real-time events (TOOL_START, TOOL_END, THINKING, PLANNING, TERMINAL_OUTPUT) drive the chat panel UI.
5. Message + response persisted to session history.

Capabilities in Agent mode:

Area	What
File ops	Read, write, edit, list, compose (atomic multi-file)
Terminal	Modal-approved shell commands, persistent sessions, test runners
Search	Ripgrep, symbol search, vector DB, web (Tavily)
Debug	Full DAP — state, stack, variables, evaluate, control
Browser	Playwright with SSRF + DNS-rebinding guards
Subagents	Delegate to 8 specialists + general-purpose
Memory	Read/write manage_core_memory + cross-session /docs/ store

Safety controls layered on top:

Control	Default	Setting
Auto-approve actions	Off	codebuddy.autoApprove
Allow file edits	On	codebuddy.allowFileEdits
Allow terminal	On	codebuddy.allowTerminal
Diff approval	Off	codebuddy.requireDiffApproval
Permission profile	standard	codebuddy.permissionScope.defaultProfile
Max tool calls	2000	codebuddy.agent.maxToolInvocations
Max events	15000	codebuddy.agent.maxEventCount
Max duration	60 min	codebuddy.agent.maxDurationMinutes

With auto-approve off, the agent pauses before every tool call for user confirmation — full visibility into intent before action.

Cancellation: an in-flight Agent turn can be stopped from the chat panel. Cancellation is cooperative — a per-conversation AbortController signals the loop, which checks between steps and unwinds cleanly (partial work already applied stays applied; you can review or undo it).

When to reach for it: feature implementation across files, refactoring, debugging with breakpoints, running tests, project-wide search-and-replace, infra/CI setup.

Plan mode

A read-only planning turn. The agent investigates and drafts a plan but cannot write — it’s fenced so a planning session can’t touch your workspace:

• No writes — write-side tools are filtered out; edits/terminal/composer are unavailable.
• No subagents, no code-interpreter REPL — both are gated off (!planMode), so there’s no task() fan-out to reason about.
• Read tooling stays rich — lsp_query, get_active_editor, query_graph, search, and diagnostics are available, so the plan is grounded in real code.
• Uses a dedicated planning system prompt.

Reach for Plan when you want the agent to think through an approach before it changes anything. When the plan looks right, switch to Agent to execute.

Switching

In the chat panel: click the mode pill to cycle Ask / Agent / Plan.

In settings: codebuddy.codeBuddyMode dropdown (Ask / Agent / Plan, default Ask) for the default mode.

Programmatically: the message carries metaData.mode. "Agent" and "Plan" route through LangGraph (Plan with the write-fenced, read-only tool set); "Ask" goes to direct provider streaming.

What both modes share

• All 9 providers work in both.
• Provider failover in both.
• Chat history persistence in both.
• Vector-DB indexing + RAG in both.
• Cost tracking in both.
• Project rules from .codebuddy/rules.md injected in both.

Related

• Architecture — how the Agent pipeline is built
• Subagents — the 9 specialists available in Agent mode
• Tools — full tool list
• Security — permission profiles + safety controls