Agent workflow

Quey's agent loop has three phases: capture (you select UI and type an instruction), execution (the agent edits your source file), and review (you approve or roll back the diff). Each phase has explicit states so you always know where in the loop you are.

Capture lifecycle

Every capture moves through these states:

State	Meaning
`pending`	Capture submitted. Waiting for the agent to acknowledge it.
`acknowledged`	Agent has picked it up and is working.
`tool_review`	Run is paused. Waiting for your pre-execution approval (Ask mode).
`file_review`	Agent finished. Files changed. Waiting for your diff approval.
`resolved`	Approved. Changes are on disk. Summary written back to the capture thread.
`dismissed`	Rejected or abandoned. No file changes kept.

Approval modes

The approval mode controls whether the agent runs immediately or pauses for your sign-off. Set it per-capture in the agent panel dropdown.

Mode	Behaviour
`Ask`	Always pause before the agent starts. You see the capture and confirm before any files are touched.
`Smart`	Pause only for runs that will edit files in your configured workspace. Safe default for mixed sessions.
`Allow`	Run immediately without pre-execution approval. Still shows the file diff for post-run review.

Note

The selected approval mode is attached to the capture payload and enforced by the MCP runner — not just the UI. Changing it mid-session affects new captures only.

File review and rollback

When the agent finishes and files have changed, the capture enters file_review. The toolbar shows an inline diff — the exact lines added, modified, or deleted.

Approve — keeps the changes on disk. The capture moves to resolved.
Reject — restores the pre-run file state from the snapshot. The capture moves to dismissed.

Rollback stores raw file bytes (not UTF-8 strings) so binary files are handled correctly. If an agent returns a file to its original state, it's treated as a modification rather than a deletion.

Tip

If no files changed, the snapshot is discarded and the capture resolves immediately — no approval step needed.

Hands-free mode

With TOOLBAR_AUTO_RUN=1, the MCP runner executes the agent automatically when a capture arrives. The loop is:

hands-free looptext

capture arrives
  → runner picks it up from the FIFO queue
  → agent executes (Codex or Claude)
  → diff appears in the toolbar
  → you approve or reject

For a fully watched loop, add uitoolbar_watch to your agent's CLAUDE.md:

CLAUDE.mdmarkdown

## Quey integration
Use uitoolbar_watch in a loop to process captures as they arrive:
while true:
  capture = uitoolbar_watch()
  # process capture
  uitoolbar_resolve(capture.id, summary="Done")

Session queues

Each browser session (tab) gets its own FIFO queue. Captures targeting the same session run in order — the agent never races itself on the same workspace. Independent sessions process concurrently.

This means you can have multiple browser tabs open against different parts of your codebase, and the agent handles each session's captures in sequence while processing them in parallel across sessions.

Note

If you send two captures rapidly to the same element, the second one waits until the first resolves. This prevents two agents from editing the same file simultaneously.