FAQ & troubleshooting

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.

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.

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 is apply: 'serve', the webpack plugin returns early in production mode, and the framework internals quello reads exist only in development builds.