Options

Every setting is declared, typed, and owned. You cannot set one that does not exist, and you cannot set the wrong type. Both are errors that name the problem.

How options work

Set them in config.toml under [options], or from code:

await neosh.opt.set("chat.show_thinking", true);
const on = await neosh.opt.get<boolean>("chat.show_thinking");
await neosh.opt.all();                    // everything declared, with types and defaults
neosh.opt.onChange((e) => { /* fires for every option, not just yours */ });

Or on the settings screen — , in the project panel, or /settings — which is built from the same registry and saves what you change into [options] in config.toml, leaving the rest of the file as you wrote it. From code, neosh.opt.save(name, value) is that verb: set, and write down; opt.set is only for now.

Plugins declare their own options through the same call the built-ins use, and a declared option is settable from config.toml like any other, including by a user who set it before the plugin loaded. opt.all() is always the complete, current list; the tables below are the ones that ship.

Agent

Chat

UI

Keys

Every picker, prompt and completion list reads the ui.keys.* family, in Neovim notation, with more than one key allowed per action:

[options]
"ui.keys.next" = "<C-n> <Down> <C-j>"
"ui.keys.prev" = "<C-p> <Up> <C-k>"
"ui.keys.page_down" = "<PageDown>"
"ui.keys.page_up" = "<PageUp>"
"ui.keys.first" = "<C-Home>"
"ui.keys.last" = "<C-End>"
"ui.keys.accept" = "<CR>"
"ui.keys.dismiss" = "<Esc> <C-c>"
"ui.keys.complete" = "<Tab> <Right>"
"ui.keys.clear" = "<C-u>"
"ui.keys.delete_word" = "<C-BS>"
"ui.keys.window_prefix" = "<C-w>"
"ui.keys.hint_delay" = 300

A widget claims these window-scoped while it is open, so they outrank global bindings and are released the moment it closes. That is what makes ^N move in a picker even though ^N is otherwise “new conversation”.

The last two are the window prefix and how long you have to hold it before it lists what follows. ui.keys.hint_delay = 0 shows the list at once; a bigger number keeps it out of the way of anyone who already knows the letters. ui.keys.delete_word moved off <C-w> when the prefix took it — a key cannot both delete a word and wait to see whether a window verb follows, because the waiting is what makes every word-delete feel late. Set them to each other’s values if you would rather have it the old way round.

Sidebar

The repository block

| git.pulls | true | The pull request on a project or worktree row: its number, its state, and its checks when they are failing or still running. Asks gh, so it needs the GitHub CLI signed in | | git.pulls.interval | 180 | Seconds between asking the forge. A pull request moves on somebody else’s schedule, so unlike the working tree there is nothing local to notice it. 0 asks only when you press the key |

Worktrees

Git prompts

Every generated name or message has a prompt behind it, and every prompt is a setting in two layers: *.instructions is appended to the built-in prompt, which is the common case, and *.prompt replaces it entirely. Instructions still apply on top of a replaced prompt, so a per-project rule layers onto your own.

[options]
"git.branch.prefix" = "feature/"
"git.branch.instructions" = "Start with the Jira key when the message mentions one."
"git.commit.instructions" = "Follow Conventional Commits."

Usage

Archive

Nothing in the archive deletes on a timer.

Plugins