OpenCues works out of the box, but a handful of habits, each drawn from the project's own docs, make it noticeably better to live with. Here they are in the order you'll meet them.
Start from the shipped defaults, not a blank tree
Let opencues install seed ~/.cues/ with the shipped cues and blanks, then edit and prune, rather than building a config tree from scratch. Seeding never clobbers files you've already edited, and the defaults double as working examples: the fastest way to write a new blank is copying the shipped example folder, and the fastest way to a new domain cue is adapting legal or medical.
Set both Cerebras and Groq keys
Both providers serve the same gpt-oss-120b weights, and with both keys present OpenCues fails over automatically on rate limits and server errors with no quality shift. Two free keys, one opencues set-key each, and the most common transient failure class disappears. Verify with opencues check-keys.
One concern per source
Config sources are built around single concerns run as isolated calls and merged by priority. Resist writing one mega-source whose prompt does everything: separate files can be individually disabled, individually prioritised, and can't steer each other's calls. A specific domain cue plus the low-priority catch-all beats one prompt trying to do both.
Commit a project-level .cues/ for team config
Configs merge across layers with project winning on name conflicts, so a .cues/ folder committed to a repo gives everyone who works in it the same cues, the same ignore list, and the same disabled sources, with personal config still applying everywhere else. Use disable: lists in the master files to mute rather than delete, so re-enabling is a one-line change. Gate merges with opencues validate --strict if the team ships config in CI.
Stay on the safe defaults for personal data
identity-context-mode defaults to safe, where the model sees token names like [FIRST NAME] and your real values are substituted on your machine after the response. Leave it there unless you have a specific reason; raw mode exists but is deliberately file-edit-only. Similarly, the free opencode-zen pool trains on input, which is why it's accepted only for the blanks bucket: treat anything typed next to a _ on that provider as public.
Launch through opencues run, and reach for doctor first
opencues run <host> checks for stale bundles and rebuilds before launching, which closes the "I updated but nothing changed" trap; direct binary launches skip that check. And when anything misbehaves, the ladder is doctor, then which, then logs --tail with debug on.
Related: How to switch models · Project-level cues · opencues run · GitHub repo