Features

Cues: alternatives on words you wrote#

As you type, words that match a cue file dim. Each holds its own alternatives, shown when the cursor reaches it. Your text is never modified without a keypress from you.

Three words fixed in one pass: press, move to the next, press again. A corrected word keeps your original as a cycle stop, which is why its count reads 1 rather than disappearing.

Blanks: type an underscore to fill in#

Type _ where a value should go. The text before it is the request.

The answer is inserted selected, so one keypress changes it and typing over it replaces it.

Script blanks: values read from your machine#

Keyword blanks run a local script instead of calling a model. Each is a folder under ~/.cues/blanks/ containing its config and script.

17% is the actual system volume, read by the script. The presses above are Ctrl+Alt+↑ three times and Ctrl+Alt+↓ once; the device follows each one.

The inline note#

A word with alternatives dims while you type. When the cursor reaches it, a note appears underneath showing what pressing _ would give you. Moving off the word, or editing it, removes the note.

How the note is drawn depends on the host: some paint it over the text, others write the note line into the text and remove it before anything is sent. Either way, what you submit is exactly what you typed.

How to read the inline note#

Format: an optional emoji, a count, then the upcoming alternatives. The lower region annotates each shape as it plays.

The three word states#

A word is normal, dimmed, or selected. Dimmed: it has alternatives. Selected: the cursor is on it, and the note is showing.

No underlines, markers, or margin icons. State is shown by colour only, so the layout of your text never changes.

The note on the status line#

Hosts with a status line (Claude Code, OpenCode, Gemini CLI, the shell) carry the note there when it cannot be painted inline; when the inline note paints, the status-line copy is suppressed so nothing shows twice.

how much has this session cost so farstatus lineπŸ’‘ Wondering what this costs? /cost shows the totals; the whole history is re-sent every turn

The loading spinner#

A blank that takes time (network lookups, model calls) shows a spinner in the slot until the value arrives, so a stalled request is distinguishable from a running one.

Status bar position (browser)#

The browser extension has no host status line, so it renders its own bar over the page. statusbar-position in ~/.cues/OPENCUES.md controls where.

ValuePlacement
bottomfull-width band along the bottom (default)
topfull-width band along the top
rightcompact panel in the bottom-right corner

One chord moves the selection between flagged words, skipping unflagged words in between.

Cursor-follow selection#

On hosts that paint the note inline, moving the cursor into a flagged word selects it for the underscore gesture and shows its note; moving out releases it. With cursor-navigate: active set, cursor arrival is a full selection everywhere. The chords remain for stepping directly between flagged words.

Cycling through alternatives#

With the cursor on a flagged word, _ replaces it with the next alternative. No underscore character is typed into your text; the keypress is the gesture. Your original word is one of the stops, so cycling far enough returns to it.

Ctrl+Alt+↑ also cycles forward; Ctrl+Alt+↓ cycles back one step.

Multi-word alternatives#

A flagged unit can be several words. The phrase is one unit: the cursor anywhere inside it selects the whole phrase, and one press replaces all of it. Two phrases on one line cycle independently.

Cursor position#

When an alternative is longer or shorter than the word it replaces, the cursor moves to the end of the new word rather than the end of the line; before or after the word, it keeps its place relative to your words.

Undo#

Type undo _ to revert the last change OpenCues made: a filled blank, a settings change, a volume or brightness adjustment. The undo request is removed with it. redo _ re-applies; a count goes further back (undo 3 _). On by default; disable with undo-mode: off.

Cycled words also revert without it: the original word is a stop in the rotation.

Taking an answer back#

An answer from a table, a calculator or a lookup can be taken back where it stands. With the cursor on the answer, the note names what you asked for:

Whiskey India Lima Foxtrot Romeo Echo Delta↳ was: nato for wilfred _ (underscore to revert)

Press _ and your request is back, with the answer waiting on the note. Press it again and the answer returns. The lookup does not run a second time.

nato for wilfred _↳ Whiskey India Lima Foxtrot Romeo Echo Delta (underscore to apply)

It is the same two-stop toggle a rewrite already has, on every host that draws notes: Claude Code, OpenCode, the shell, Gemini CLI and Chrome's rich composers.

Editing a flagged word#

Typing into a flagged word removes its alternatives and its note. Other flagged words on the line keep theirs.

Alternatives that follow the word#

Inserting or deleting text before a flagged word moves its position in the line. Its alternatives and cycle state move with it, tracked by content rather than by offset.

Free-form blanks#

A line with no blank keyword is sent to the model as written, and the answer is shaped to fit the sentence: a word where a word belongs, a number where a number belongs.

Transforms: an instruction after the text#

Text first, instruction second, then _. The text is rewritten per the instruction; the instruction and underscore are removed.

The original line is kept as a cycle stop, so one press restores it.

The settings blank#

opencues settings _ inserts a setting and its current value as a pair of cycle-able words: cycle the left word to change which setting, the right word to change its value. Changes are written to ~/.cues/OPENCUES.md as you cycle.

Lookup blanks: weather, definitions, prices#

Shipped keyword blanks cover weather, dictionary definitions, stock and crypto prices, location, country facts, and Hacker News headlines. Each is a folder under ~/.cues/blanks/.

Calculators and reference tables#

With table-lookups-mode: on in ~/.cues/OPENCUES.md, a _ after a calculation or a look-up is answered by code on your machine, with no model call and no network. The answer is arithmetic over the words you typed, or a row in a table that ships with OpenCues, so it cannot be wrong the way a generated answer can. Off by default.

You typeYou get
3pm london in tokyo _23:00 <today> in tokyo (GMT+9, UTC+09:00)
days between 3 march and 19 september _200 days (28.6 weeks)
tip 15% on 64.20 _tip 9.63 Β· total 73.83
monthly payment on 250000 at 6% over 30 years _1,498.88/month (total 539,595.47, interest 289,595.47)
nato for wilfred _Whiskey India Lima Foxtrot Romeo Echo Delta
cron for every monday at 9 _0 9 * * 1 (at 09:00 on Monday)
signal 15 _signal 15: SIGTERM terminate, the polite kill (exit code 143)
default port for postgres _postgres: 5432
hex for tomato _tomato: #ff6347

The answer replaces the request and anything written before it stays. The families cover dates and durations, time zones, percentages and money, unit conversions, number formatting, geometry, physics, fitness and media, encodings, and text work over your draft. A request no table knows fires nothing, and the _ goes to the normal lookup instead.

The note blank#

note add saves a snippet to ~/.cues/NOTES.md; note <words> _ retrieves the best match. Matching runs locally; note content is never sent to a model.

note ffmpeg _ then inserts ffmpeg -c copy out.mp4, label stripped, ready to edit.

Underscores in markdown#

Default (blank-trigger-mode: immediate): _ triggers as soon as you type it. In markdown, where _like this_ is emphasis, set blank-trigger-mode: spaced: a blank then only triggers when a space follows the underscore, so _italic_ is left alone and a trailing _ still works.

When requests are sent#

The two mechanisms send differently. Cues are automatic: your text is analysed after a short typing pause, so a half-typed word is never analysed, and there is no submit action. Blanks are user-invoked: the _ is itself the request, so it dispatches immediately, with no pause.

Date and arithmetic checks#

A weekday paired with a date is checked against the calendar; a total is checked against its parts. The model only classifies what kind of claim the sentence makes; the correction is computed locally, so the check cannot report a false contradiction. On by default since v0.4.3.

The corrected weekday is offered as the next cycle stop. Nothing changes unless you press.

Sentence rewrites#

A cue file with sentence scope flags whole sentences and offers full rewrites, cycled with the same keys as a single word. The shipped more-formal cue rewrites casual sentences; its config excludes coding terminals via not-on-host:, so it runs in the shell input box and, in the browser, on the sites its allow-list names (LinkedIn and web email). sentence-cues-mode: on by default.

The note names the cue rather than previewing the rewrite, which is too long to fit under the line.

Agent tasks: a persistent instruction#

End a line with agentically <instruction> _ and the instruction is applied to the whole text, then re-applied each time you pause typing. Every word it changes is dimmed and carries your original as an alternative, so any edit reverts with one press.

Markdown styling#

Model output containing markdown emphasis (**bold**, *italic*, backtick code) is converted to the host's real styling before insertion. No literal asterisks reach your text.

Settings in plain words#

Describe a settings change and end with _. The request text is replaced by the setting name and its new value, as the same cycle-able pair the settings blank produces. Text before the request is preserved.

This route can only reach settings. It cannot invoke script blanks (volume, brightness), so text pasted into your editor cannot trigger a program through it.

Identity fields: names sent, values kept local#

Store personal fields (email, phone, city, sign-off) in ~/.cues/IDENTITY.md, edited directly or via opencues identity. In the default mode (identity-context-mode: safe) the model receives field names only; values are substituted into the answer locally, after it returns.

The substitution runs in both directions: a value you typed yourself is replaced by its field name before the request is sent.

Calendar context: times sent, titles kept local#

Add an iCalendar feed with opencues calendar add <url> and availability questions are answered from your busy times. Event times are sent; titles and locations are replaced with numbered tokens and restored locally in the answer. Without a feed, the feature sends nothing.

Field context (browser)#

With ambient-context-mode: on, a blank in a browser form field also sends the field's label, its placeholder, and the page title, so _ in a field labelled "postcode" answers with a postcode. Nothing else on the page is sent: not other fields, not their values, not the page text. Off by default; browser only.

postcode: M1 4BT

Blanks as context for other blanks#

A lookup blank can declare as-context: safe, joining a catalog that free-form blanks and transforms draw on. In the default mode the model receives the blank's token only; your machine substitutes the live value (the forecast, a price) into the answer locally, the same mechanism identity fields use. Shipped opt-ins: weather, stocks, crypto, Hacker News. The note and dictionary blanks declare as-context: off (personal stores), and the action blanks (volume, brightness) decline because control surfaces should not feed prompts. Global switch: blank-context-mode, default safe.

What ships installed#

opencues install <host> seeds ~/.cues/ with a working set: the spelling cue, the formality cue, the calendar cue, and blank folders including volume, brightness, weather, dictionary, stocks and notes. They are ordinary files, editable and deletable like anything you add.

Word claiming#

Each cue file declares which words it matches. A word is claimed by exactly one file, and only that file's instructions are sent to the model for it, so one file's prompt cannot affect a word another file claimed.

Shipped fileClaims
spellingany word no other file claimed, which is why typos are caught in any sentence
more-formalwhole sentences, in the shell and on allow-listed sites
calendarsentences mentioning a time, once a feed is added

Adding a subject is one CUE.md file. No code changes.

Spelling#

The shipped spelling file is the catch-all in that table: it matches every word and sits at the lowest priority, so it claims whatever no other file wanted. That combination is why a typo is caught in any sentence, and why a word one of your own files claimed is never treated as one.

A misspelling dims where you typed it. The note under it reads ✍️ receive: the mark that says the word is wrong, and the correction. Press underscore and it reads was: recieve, one press from the word you wrote.

Local answers#

Alternatives that can be computed locally are computed locally and appear without network latency: a weekday checked against its date, a value read from your machine. Only the remainder is sent to a model.

Hand-written tip packs are one local source: each host ships one covering its own commands. The date and arithmetic checks are another; their corrections are computed, not fetched.

Cue priority#

When two files match the same word, the higher priority: value wins. Shipped values: calendar 90, more-formal 85, spelling 10. Spelling is lowest so it only claims words no other file wanted, and a subject file's term is never treated as a typo.

Where files are read from#

Two locations, checked in order. A project can ship its own vocabulary in version control; where both define the same name, the project wins.

PathScope
<project>/.cuesthis project; wins on conflicts
~/.cuesuser-level, everywhere else

Hot reload#

Config files are re-read while a host runs. A saved change is live by the next keystroke, roughly 2 seconds later, with no restart or reload command.

Shared cue files#

A cue file can be sourced from a shared location instead of each machine keeping a copy, so a team edits one vocabulary.

Asking once per word#

A word that already has alternatives is excluded from later requests. Requests stay small, and a word you just cycled to is not re-analysed as new input and offered alternatives to itself.

Cue files from a chat session#

A Claude Code skill and an OpenCode plugin can write .cues/CUES.md from an ongoing conversation, turning the session's recurring vocabulary into cue sources. The output is a normal cue file: editable, deletable.

Missing keys#

A _ that no model source can serve, because the selected provider has no key or no key is set at all, gets the failure written into the line, selected, so cycling back restores the bare blank. Errors have one surface: the line itself.

Provider failures#

Failures are classified from the response, and a classified, fixable failure is written into the line at the _ as a bracketed message naming the fix. The classes: rejected key (401/403), endpoint 404, a model the provider does not serve, out of credits, rate limit (429), network failure, bad request (400); each has its own message, and it stays until you edit or cycle it away. Unclassified failures (a provider's own 5xx, malformed output) stay silent and retry on the next change.

Reasoning effort#

max-thinking: on (default) lets reasoning models use their configured effort ceiling; off reduces effort for faster, cheaper answers. The setting only lowers effort below the ceiling, never raises it. Models without a reasoning-effort parameter ignore it.

Per-bucket model routing#

Three request kinds route independently: cues-llm-provider (word and sentence suggestions), auditors-llm-provider (background rewrites), blanks-llm-provider (underscore requests), each with a matching -model scalar in ~/.cues/OPENCUES.md. opencues doctor prints the effective provider and model per bucket and which setting decided it.

Using a Claude subscription#

With the claude CLI installed and signed in, a bucket can be set to claude-code-cli to route through an existing Claude Pro or Max subscription rather than a separate ANTHROPIC_API_KEY. Set per bucket, so word suggestions can stay on a faster provider.

The six hosts#

A cue or blank runs on every host unless its config narrows it with on-host: or not-on-host:. In the browser, on-site: additionally scopes by site.

HostSurface
Claude Code, OpenCode, Gemini CLIthe coding terminal's input
shell (oc-shell)an input box over your own terminal
Chrome extensiontext fields on web pages
Windowsnative Windows text fields, system-wide (Notepad, Explorer, Win32 apps), via a thin shim over the same WSL runtime

Plain input fields#

Plain <input> and <textarea> elements cannot render per-word colour, so features that depend on it (cycling, dimmed words) are disabled there rather than left broken. Underscore blanks that need no cycling still work; stepped or picked blanks (volume, the settings blank) and word cues stay off. Rich editors (Gmail, Reddit, ChatGPT) get the full set.

How the browser reads your files#

A browser extension cannot read your disk. opencues install chrome-host installs a local process that watches ~/.cues/ and pushes changes to the extension, so edits reach open tabs without an export step.

Katas: guided walkthroughs#

start kata 1 _ begins a guided run through a workflow inside the editor. The status line shows the current step; progress is detected from what you type and press, not from you confirming steps. Esc three times exits unconditionally. Coaching requires a model key; the steps and the exit work without one.