Agent is where a capture stops being a note to yourself and becomes an instruction to something that can act on it. This is how the composer, the modes, the approval system, and the streaming panel actually work.

Providers and models

Agent supports three providers — Claude, Codex (OpenAI), and Cursor — each with its own model list (for example, Claude offers Haiku, Sonnet, and Opus tiers). Provider, model, approval mode, and agent mode are all persisted per session via persistAgentSettings(), so switching which element you're pointing at doesn't reset your setup back to defaults each time.

Three modes: Ask, Plan, Build

Every capture runs through one of three modes:

• Ask — read-only, no edits. For understanding what something does without risking a change.
• Plan — the agent proposes an approach before touching anything.
• Build — full run: read, edit, execute.

Shift+Tab cycles Ask → Plan → Build, the same binding Claude Code uses in the terminal, so the muscle memory carries over if you already work that way.

Approval: alwaysAllow vs. smart

There's a single toggle in the composer between always allow and smart approval. It matters more than it looks like it does. With smart approval on, the agent isn't gated on every tool call — Read, Grep, Bash, and everything else auto-allow, because the meaningful review point isn't “did the agent look at a file,” it's “is the agent about to write one.” Only Write, Edit, and MultiEdit calls pause. When one does, Quey computes the diff before the write happens — reading the current file, applying the same edit semantics Claude Code itself uses for single vs. all-occurrence replacement — and shows you that diff with Approve/Reject buttons. Nothing lands on disk until you act on it.

This is a deliberate trade: gating every tool call would make Ask-style exploration painfully slow to watch, while gating nothing would make Build indistinguishable from “just trust it.” Smart mode gates the one action that actually needs your eyes.

Streaming: what you see while it's running

While a run is active, the panel shows a single line — an animated dot-matrix loader, the current step's label, and elapsed time — rather than a growing list of tool calls. The loader's visual state maps to the run's phase: sending and initial dispatch render as “generating,” thinking renders as itself, and both tool_review and file_review render as “reviewing.” Once the run resolves, a separate collapsible activity card appears with the full step-by-step trail — it's deliberately absent during streaming so the live view stays to one line instead of turning into a scrolling log.

Running more than one at a time

You're not limited to one capture in flight. Up to five agent sessions can be tracked concurrently — select an element, send it, then select another and send that too, without waiting. Go past five and the oldest background session (never the one you're currently focused on, and never the incoming one) gets quietly evicted from the panel — but eviction only stops Quey from tracking it locally. The run itself keeps going server-side and stays visible in history, so nothing is actually lost, just no longer pinned to the panel.

Cancelling actually cancels

Hitting Stop and losing focus on a session are two different things, and Quey used to blur that line: stopping a run only ever untracked it locally while the provider call kept running in the background, so the “processing” status in history quietly lied about what was happening. Stop now aborts the actual provider call server-side, not just the panel's view of it. There's a second, subtler fix alongside it: a status poll that was already in flight when you hit Stop could land afterward and resurrect state that cancellation had just cleared. That race is closed — a poll response for a session nothing is tracking anymore gets silently discarded instead of being applied.

From diff to commit

Once an agent run has made changes, the panel aggregates them into a reviewable diff — insertions/deletions totals, changed-file list — independent of which individual capture in a thread produced which change. From there, two actions are available directly in the panel: commit the thread's changes to the repo (optionally pushing in the same action), or open a pull request. You don't have to leave the browser tab to turn an agent's work into a real commit.

The MCP bridge and auto-run

When quey-mcp is running locally, every capture posts to the bridge automatically, and — as of the last release — auto-run is on by default: an agent kicks off as soon as a capture arrives, rather than requiring you to explicitly enable it. QUEY_CODEX_CWD is still a required, explicit setting naming exactly which repository directory the runner is allowed to touch, which is what makes defaulting auto-run to on safe rather than surprising. Set QUEY_AUTO_RUN=0 if you'd rather trigger runs manually.

Tips

• Default to smart approval until you trust a given task's scope — you only see a prompt when a file is actually about to change, so it costs you almost nothing on Ask/Plan runs.
• Use Ask for anything where you just want an answer — it genuinely cannot edit anything, so it's the safe default when you're not sure what a component does yet.
• Fire off several captures in a row instead of waiting on each one — the 5-session cap exists so you can parallelize, not so you're stuck babysitting one run at a time.
• If you Stop a run you regret starting, trust that it's actually stopped now — there's no lingering background process still editing files after the panel says otherwise.
• Pair Agent with context boxes from Select: once something's selected, plain clicks on other elements — no modifier needed — add them as numbered supporting context instead of replacing your selection, for when the fix isn't really about one element in isolation.