Plugin options

The Vite and webpack plugins take the same options, and so does @quello/next — through withQuello(), or as props on <Quello />. Everything here is a project decision, set in code — the toolbar's own settings panel is for per-developer preferences instead.

quello({
  enabled: true,
  picksFile: '.quello/picks.json',
  shortcut: 'alt+q',
  visibilityShortcut: 'alt+shift+q',
  visible: true,
  textLimit: 120,
  writeAgentFile: true,
  agentFile: 'AGENTS.md',
  gitignorePicks: true,
  htmlMode: 'truncated',
  htmlLimit: 1000,
  theme: { /* see below */ },
})

enabled

boolean — default true. Turns the plugin off without removing it from the config.

In @quello/next it can only ever turn quello off: production is off regardless, because the picks endpoint there is a route handler in your own app rather than dev-server middleware, and it writes to disk.

picksFile

string — default .quello/picks.json. Where picks are stored, relative to the project root.

shortcut {#shortcut}

string — default 'alt+q'.

A whole combination, not a key with Alt assumed around it:

quello({ shortcut: 'alt+q' })          // the default
quello({ shortcut: 'ctrl+shift+p' })   // no Alt in sight
quello({ shortcut: 'cmd+k' })          // cmd, command, meta, super and win all mean Meta
quello({ shortcut: 'f2' })             // no modifier at all

Parsing ignores case and spaces; opt/option mean Alt, control means Ctrl, esc means Escape. A string naming no key falls back to alt+q.

Matching uses the physical key code as well as the character, because holding Alt rewrites the character on macOS — Alt+Q arrives as œ — and a shortcut comparing only characters would never fire there.

visibilityShortcut {#visibilityshortcut}

string — default 'alt+shift+q'.

Takes quello off the page and brings it back, for when the toolbar is sitting on the thing you are trying to look at. Declared exactly like shortcut, and parsed by the same code.

quello({ visibilityShortcut: 'ctrl+shift+h' })

Hiding leaves picker mode too — picking with nothing drawn would have you clicking blind — and showing again does not resume it. Picks are untouched: they are on disk, and their badges come back with the overlay. Pressing the picker shortcut while quello is hidden brings it back as well, since that is plainly what was meant.

visible

boolean — default true. Whether the overlay is on the page at startup.

false loads quello but keeps it out of the way until visibilityShortcut summons it. Nothing is unmounted, so picks made earlier are still restored and reappear with the overlay.

quello  Alt+Q to pick · Alt+Shift+Q to hide and show quello

textLimit

number — default 120. Characters of element text kept per pick.

writeAgentFile

boolean — default true. Whether to write the quello section into an agent instructions file on first run.

agentFile {#agentfile}

string — default 'AGENTS.md'.

quello({ agentFile: 'CLAUDE.md' })                        // Claude Code only
quello({ agentFile: '.github/copilot-instructions.md' })  // directories are created
quello({ writeAgentFile: false })                         // write nothing

AGENTS.md is the open convention Codex, Cursor, Zed and Aider read, and Claude Code reads it alongside its own CLAUDE.md — so one file reaches every agent.

The section is fenced in <!-- quello:start --> / <!-- quello:end --> and is never rewritten, so your edits stick. Calling quello twice with two different values writes both files.

gitignorePicks

boolean — default true.

Adds the picks directory to your .gitignore on first run, since picks describe the browser session in front of you rather than the project:

# quello — visual element picks (generated, safe to delete)
.quello/

It appends once and never duplicates: an entry already ignoring that path in any of its usual spellings — .quello, /.quello/, .quello/* — counts as done. If you have no .gitignore, one is created. The pattern follows picksFile, so a custom location is ignored instead of .quello/.

Set it to false to keep quello out of a file you own. The CLI equivalent is --no-gitignore.

htmlMode / htmlLimit

'none' | 'truncated' | 'full' — default 'truncated', and number — default 1000.

The starting point for the HTML setting. Once a developer chooses a mode in the panel, their choice wins.

theme {#theme}

How the outlines quello draws on your page look. Six values, everything else derived from them:

quello({
  theme: {
    hoverColor: '#0ea5e9',                  // hover outline; its fill and label follow
    hoverBorderWidth: 3,                    // a bare number means px
    pickedFill: 'rgba(16, 185, 129, 0.12)', // inside a picked element
    pickedBorderColor: '#10b981',
    pickedBorderStyle: 'solid',             // solid | dashed | dotted | double
    pickedBorderWidth: 2,
  },
})

Derived rather than configured: the hover fill (color-mix at 12% of hoverColor) and the element label's background. Set the hover colour and all three stay coherent.

Values become CSS custom properties, so any valid CSS value works — tomato, 0.125rem, a color-mix() of your own. Values carrying ;, braces or comment markers are refused and the default for that option stands.

Next only

Two more, for @quello/next, where the picks endpoint is a route in your own app rather than dev-server middleware.

basePath

string — default /api/quello. Where the route handler is mounted, and therefore what <Quello /> points at. app/api/quello/[...quello]/route.ts on disk; change both together, or let scaffoldRoute follow it for you.

scaffoldRoute

boolean — default true. Write the route handler when it is missing. It is two lines, and Next gives a package no way to add a route on its own — so quello writes them rather than asking you to. An existing file is never touched.