FAQ & troubleshooting

Isn't this what the inspector already does?

Svelte Inspector, Vue DevTools and Nuxt DevTools all let you hover an element and click it — the same gesture as quello, sometimes on the same key. What differs is the click itself: the inspector opens your editor at that line and keeps nothing; quello appends the pick to .quello/picks.json and your agent reads it from there.

That one difference is where everything else comes from. You can pick several elements in one pass instead of one at a time. Picks survive a reload and a route change, because the runtime re-resolves each stored selector. Each pick carries the selector, text, attributes and computed styles, plus the component, file and line where the framework exposes them — not just a location. And you can attach a note to any pick and say "resolve the picks", which no inspector has a place for.

Use the inspector when your next step is open this file. Use quello when it is tell the agent which ones I mean.

The toolbar does not appear

Check, in order:

1. Is the dev server the one running? The plugins are development-only by design and are absent from a production build.
2. Does your framework render its own HTML? Nuxt, SvelteKit and Astro need the virtual:quello import; the plugin alone is not enough.
3. Is the runtime being served? Open /__quello/client.js in the browser. A 404 means the plugin is not attached; a 500 means the package was not built.

Picks are not saved

Open /__quello/picks directly. If it 404s, the endpoint is not attached — with webpack this usually means devServer is not in the config, and with the CLI that the page is pointing at the wrong port.

The picker keeps working without the endpoint: badges still appear, they just do not persist.

The shortcut does nothing

The page needs focus — click it once after a reload. If you changed the shortcut, remember a combination with no Alt, Ctrl or Cmd is deliberately ignored while you are typing in a field.

Copying to the clipboard fails

Browsers require a real user gesture to write to the clipboard. A pick made by a real click works; a pick made programmatically from the console reports Copy failed, which is the browser refusing, not a bug.

No component name on my picks

Expected for Solid, Astro static pages, plain HTML and anything else without a framework runtime in the browser — see compatibility. The selector, DOM path and text are still there, and an agent can find the code from those.

No line number on React picks

You are on React 19, which removed the _debugSource annotation quello read the line from. Its replacement, owner stacks, still yields the file — and quello reports it — but the line in a stack frame belongs to the compiled module, and a browser does not run error.stack through source maps. Reporting it would point at the wrong element, so quello does not.

This follows the React version, not the bundler: Next's App Router bundles React 19 whatever your package.json says. The component name and file are there either way, which is enough for an agent to find the element. On React 19 that file arrives module-relative — /src/components/Card.tsx rather than an absolute path — because it comes from the stack frame rather than from a compiler annotation.

The badge is in the wrong place

Badges are re-anchored every animation frame, so they follow scrolling and sticky elements. If one is stuck, its element was probably removed from the DOM — a filtered list, an unmounted route. The badge hides itself rather than drawing at the origin, and comes back if the element does.

The MCP server reports no picks

It is reading a different .quello/picks.json than the one your dev server writes. Your editor launches an MCP server from whichever directory it happens to be in, and with no flags the server climbs from there looking for an existing picks file, then for a package.json or .git.

Its startup banner, in your editor's MCP log, says which one it settled on:

  quello mcp   stdio
  root         /path/to/app (discovered)
  picks        /path/to/app/.quello/picks.json

If that is the wrong project — a monorepo with several apps, most often — pin it with --root. — not created yet on that line means the path is right but nothing has been picked yet.

Should I commit .quello/picks.json?

No — and you do not have to do anything: quello adds .quello/ to your .gitignore on first run. Turn that off with gitignorePicks: false.

Your agent file is the opposite: AGENTS.md belongs in the repository, since it tells every agent on the project how to read the picks.

Does it work in production?

No, deliberately. The Vite plugin contributes nothing to a production build, the webpack plugin returns early in production mode, and the framework internals quello reads exist only in development builds.