Configuration

Configuration is optional. cueloop ships with sensible defaults and reads a TOML file only to override them.

Where the file lives

cueloop looks for a user config in this order, and stops at the first it finds:

$CUELOOP_CONFIG
${XDG_CONFIG_HOME:-~/.config}/cueloop/config.toml

If the current repository has a .cueloop/config.toml, it is layered on top of the user config. Later layers win: built-in defaults, then user config, then repo config. A file that fails to parse is ignored, and the defaults stand.

[vcs]

Use provider = "auto" to select JJ in a colocated checkout and Git in a Git checkout. Set provider = "git", "jj", or a registered adapter ID to choose one explicitly. Extensions load from the user config only.

[vcs]
provider = "auto"

See Review diffs and VCS extensions.

[keys]

Every action is rebindable. A value is a single key combo or an array of them.

[keys]
down = ["j", "down"]
comment = ["c"]
submit = ["return", "enter"]

Action	Default	What it does
down / up	j,down / k,up	move the cursor
top / bottom	g / G	jump to top / bottom
span	v	start a span selection
comment	c	add a comment
cut	x	cut the selected span
edit	e	edit the body (inline for a plan, $EDITOR for a diff)
next_annotation / prev_annotation	n / p	move between comments
delete_annotation	backspace	delete a comment
submit	return,enter	submit the review
share	S	share the plan
quit	q	quit
walk	w	start the walk wizard
review_cycle	b	cycle the review panel mode
review_wider / review_narrower	] / [	resize the review panel

In the thread view a letter types a comment, so the structural commands live in nav mode: press esc, then a bare letter acts. There is no leader or modifier chord to configure. See Keyboard & mouse.

[ui]

[ui]
auto_close = "off"        # "off", 0 (instant), or N seconds
editor = "nvim"           # overrides $EDITOR for the edit action
review_width = 34          # review panel width in columns (24-50)
review_state = "expanded" # "expanded", "compact", or "hidden"
diff_view = "split"       # "split" or "stacked" (the wide Changes layout)
default_message = "approved" # the message the submit card opens on
theme = "cueloop"         # a built-in theme preset (see below)

Key	Type	Default	Meaning
auto_close	"off" or number ≥ 0	"off"	after sending: "off" prompts, 0 closes at once, N counts down N seconds
editor	string	$EDITOR	editor for long comment bodies
review_width	number, clamped 24-50	34	width of the expanded review panel
review_state	expanded | compact | hidden	expanded	review panel mode
diff_view	split | stacked	split	the wide Changes layout: old|new side by side, or one stacked column. A narrow pane is always stacked. unified still loads as stacked.
default_message	comment | approved | changes_requested	approved	the message the submit card opens on
theme	a preset name (see [theme])	cueloop	the built-in color theme; also settable in Settings › Appearance

review_width and review_state also persist as you adjust them in the UI, so your last layout carries over between runs.

[review]

[review]
skill = "code-review"
workspace = "worktree" # "worktree" or "current"

The review skill inspects a pull request before cueloop opens the Thread. Worktree mode keeps the current checkout untouched. Current mode refuses to run unless the checkout is already at the pull request head.

[[actions]]

On a plan, v marks a span and shows the marker toolbar (comment · cut · actions). Pressing a opens the quick-actions list: a set of preset comments you pick with j/k and ⏎, each inserting its prompt as a comment on the span. Every entry is a [[actions]] table with a required prompt and an optional metadata block that is appended after a blank line.

[[actions]]
prompt = "Needs a test"

[[actions]]
prompt = "Extract the duplication"
metadata = "pull the shared branch into one helper"

Key	Type	Meaning
prompt	string, required	the comment body inserted when you pick the action
metadata	string, optional	extra lines appended after the prompt

Defining any [[actions]] replaces the defaults; a table without a prompt is ignored. With none configured, the built-in prompts stand:

#	Default prompt
1	Zoom out, research in depth
2	Restate simplified
3	Out of scope
4	Let's chat about this
5	Prototype this
6	Ensure 0 regressions
7	Consider existing repo patterns

[theme]

Pick a built-in theme with [ui] theme, then override individual tokens here. The presets are cueloop (the branded default, transparent so your terminal background shows through), rose-pine-moon, catppuccin-mocha, tokyo-night, gruvbox-dark, and nord (each paints its own opaque background). A [theme] override layers on top of the chosen preset, so a hand-tuned token survives a theme switch.

Override any theme token with a colour string. Unset tokens keep their default.

[theme]
accent = "#cba6f7"
green = "#a6e3a1"

By default the canvas and flat chrome are transparent: cueloop paints no background there, so your terminal's own background - including any transparency or blur it renders - shows through. The default text colours assume a dark-ish terminal. For an opaque look, set the surfaces yourself:

[theme]
background = "#1f1f29"
panel = "#1a1a23"

Tokens: background, panel, elevated, border, text, textMuted, textDim, accent, accentInk, green, red, blue, warning, cursorBackground, markCommentBackground, insertedForeground, deletedForeground, insertedBackground, insertedEmphasisBackground, deletedBackground, deletedEmphasisBackground, backdrop. The four *Background tokens are the diff's line bands and the brighter tint under a changed word. Unknown tokens are ignored.

[experimental]

Opt-in features, all off by default.

[experimental]
prototype_pixels = true   # render a prototype as a pixel mockup instead of the text design doc
thread_agent = true       # enable the local owner’s experimental agent conversation

Key	Type	Default	Meaning
prototype_pixels	boolean	false	render an HTML prototype as a kitty-graphics pixel mockup; the default is the Markdown design doc

thread_agent is a boolean, defaults to false, and gates both the Thread UI and local daemon agent API. It is unavailable in shared views or to collaborators. Enable it in user or repository configuration and restart cueloop; Ctrl+Enter invokes the agent, while Option+Enter saves an editable comment.

[thread]

Choose the preferred harness for new owner-hosted Threads:

[thread]
harness = "pi" # pi or fx

With thread_agent enabled, open Settings → Thread → Harness and click to switch the current Thread. Rapid clicks keep the latest requested harness; an in-progress handoff finishes before another begins. The active turn finishes first. The outgoing harness prepares continuation context, and the next request uses the incoming harness. The transcript and comments stay in the same Thread. A failed handoff keeps the outgoing harness and displays the error.

Both harnesses use the durable execution runtime. Pi uses the owner's model credentials; fx uses its own authenticated ACP process. Switching does not transfer credentials or provider settings. An fx request interrupted after dispatch is reported as interrupted and is not sent again automatically.

Select the daemon default at startup with cueloop --harness pi or cueloop --harness fx. Change a running daemon with cueloop restart --harness fx. An explicit startup choice overrides the TOML preference until the daemon restarts. A launcher whose requested default differs from the running daemon reports the restart command. Harness selection is owner-only.

[integrations.obsidian]

Export resolved reviews into an Obsidian vault.

[integrations.obsidian]
vault = "~/notes"
folder = "cueloop"
filenameFormat = "{YYYY}-{MM}-{DD} - {title}"
separator = "space"
exportOn = "manual"

Key	Default	Meaning
vault	first vault found	vault path
folder	cueloop	destination folder in the vault
filenameFormat	{YYYY}-{MM}-{DD} - {title}	note filename template
separator	space	filename word separator: space, dash, or underscore
exportOn	manual	when to export: approved, any message, or manual

Environment variables

Variable	Default	Used for
CUELOOP_CONFIG	-	path to your user config file
CUELOOP_HOME	~/.cueloop	local cueloop data directory
CUELOOP_GH	gh	the GitHub CLI used to fetch and post PR reviews
EDITOR	-	editor for the edit action (overridden by [ui] editor)