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',
  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.

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.