How Quey works

Quey connects your browser selection to your code editor through three steps: capture, handoff, and approval. Understand the flow so you know what context your agent is seeing and why certain selections work better than others.

Captures

A capture is the structured payload Quey sends to your agent when you select an element and type an instruction. It includes:

• Element context — the component name, tagname, accessible name, and bounds
• Source hint — if available, the file path and line number where the component is defined
• DOM path — the selector path to the element on the live page
• Computed styles — current colors, fonts, spacing, and layout values
• Your instruction — what you want the agent to change
• Screenshot — a visual snapshot for context (optional for style edits)

Once sent, a capture goes through these states:

• Pending — waiting for the agent to start work
• Acknowledged — the agent has read the capture and started processing
• Running — the agent is making changes or waiting for approval
• Resolved — the agent finished and you approved (or rejected and rolled back)
• Dismissed — you cancelled the capture

Selection & context

The quality of your selection directly affects how well the agent can find and edit the right code. Here's how:

Source file detection

If your site is built with React, Vue, Svelte, or Next.js, Quey reads the component tree from the live page and includes the file path and line number in the capture. This gives the agent a head start: it doesn't have to search for the file, it can jump straight to the right line.

Selection scope

Select as close to the code you want to edit as possible. If you select a button's text instead of the button itself, the context includes the text but not the button's styling — which makes it harder for the agent to change button colors.

Semantic vs. technical

The DOM path (e.g., .btn-primary > span) is great for debugging. The component name (e.g., <Button>) is what the agent uses to find the file. Both are included; the agent chooses the best one.

Agent handoff

Once you send a capture, here's what happens:

1. The extension sends the capture to the MCP bridge over HTTP.
2. The MCP bridge queues the capture in the current session.
3. Your agent polls the MCP bridge for pending captures (or subscribes to a stream if it supports it).
4. The agent reads the capture through quey_get_pending or quey_get_capture tools.
5. The agent uses the source file hint or DOM path to find the component.
6. The agent generates an edit based on your instruction and the element context.
7. The agent updates the MCP bridge with a quey_resolve call, including a summary of what changed.

Approval & rollback

After the agent makes a change, the toolbar shows a diff. You have three options:

• Approve — the agent writes the changes to disk and marks the capture as resolved. You can still undo in your editor.
• Reject — the agent rolls back any uncommitted changes. If you made manual edits, you can still keep them.
• Edit first — close the diff, edit the code in your editor, then click Approve to commit the capture without re-running the agent.

If a change looks wrong, rejecting doesn't erase your work — it just tells the agent the edit wasn't what you wanted. You can select the same element again and try a different instruction.

Sessions

A session groups captures for a single browser tab or workspace. Each session has its own queue, so:

• Captures in different tabs don't block each other.
• You can send multiple captures in one tab and the agent processes them in order.
• Sessions persist in the toolbar even if you refresh the page (unless you clear storage).

You can see all active sessions by opening the toolbar and looking at the history. Each session shows the count of pending, running, and resolved captures.

Example: changing a button color

Let's walk through a real example:

1. You select a button on your local site. Quey detects it's <Button> from src/components/Button.tsx:42.
2. You type: "Change the button color to red."
3. You click Send.
4. The extension sends the capture to the bridge: element context, file path, instruction, and screenshot.
5. Your agent polls the bridge and reads the capture.
6. The agent opens src/components/Button.tsx and looks at line 42.
7. The agent finds the color property and changes it from color: blue to color: red.
8. The toolbar shows a diff: - color: blue → + color: red.
9. You click Approve. The file updates on disk and in your running site (if you have HMR).
10. The capture is marked as resolved and moved to history.

No manual file searching, no copy-pasting selectors, no back-and-forth in chat. The agent had everything it needed in one click.

Next