ncode CLI Configure
Terminal, themes and mouse
ncode runs in any terminal on macOS and adapts to what the terminal can show. Everything on this page is a setting of this terminal, kept in cli.json beside the database, so the desktop app is not affected.
Supported terminals#
The full glyph set, with thin rails and fine progress bars, needs a truecolor terminal whose TERM names Ghostty, kitty, WezTerm or iTerm. Everywhere else, including Terminal.app and inside tmux or GNU screen, ncode draws a plainer glyph set with the same layout and keys.


Dark and light#
/theme dark and /theme light switch at once and are remembered. At launch the theme is chosen in this order:
NCODE_THEME=darkorlight, while it is set;- the theme you chose with
/theme(or in Settings → Appearance); - the desktop app's light or dark mode;
- dark.
/theme also takes a palette name. Eight palettes, each with a dark and a light variant, come from the desktop app: carbon (the default), aurora, dusk, ember, fjord, graphite, obsidian and paper. /theme ember picks the palette and keeps the current dark or light mode, and /theme dark or /theme light keeps the palette. The palette is the terminal.palette setting. Secondary text is drawn at a readable contrast; the terminal.colors setting (Colours in Settings → Appearance) has a high_contrast choice that makes it stronger still.

Plain glyphs and monochrome#
NCODE_ASCII=1, or Glyphs in Settings → Appearance, draws plain ASCII glyphs, for a terminal or font without the symbols.NO_COLORgives a monochrome screen; Colours in Settings → Appearance sets colour too.- Ambiguous-width characters (narrow or wide) fixes misaligned borders in fonts that draw box characters two cells wide.
- Reduced motion is a switch on the same page.
- Accent colour takes a
#RRGGBBvalue.
These apply at the next launch.

Wheel, mouse and selection#
By default ncode does not ask the terminal for mouse reports. The terminal keeps its own selection, so you can drag to select text and copy it, and the mouse wheel still scrolls the transcript (or the pager or overlay that is open), because ncode turns on alternate scroll (CSI ? 1007 h): the terminal sends arrow keys for wheel notches while a full-screen program is showing, and ncode reads a burst of arrows in one go as the wheel. A single arrow key is still a key. The wheel moves three lines a notch (Lines per notch, terminal.wheel_lines, applies in both modes).
/mouse onturns on wheel reports instead: clicks and the wheel go to ncode, and you select text by holding Shift while dragging (in Terminal.app and iTerm2, hold Option)./mouse offgoes back to the default.NCODE_MOUSE=1or0wins over both for the next launch, and theterminal.mousesetting keeps your choice.- Known limit: a terminal that sends exactly one arrow key per wheel notch looks like you pressing ↑ or ↓, so the wheel can walk through your earlier prompts instead of scrolling. If that happens in your terminal, use
/mouse on.
Notifications and the window title#
When an approval or a question needs you, or a turn you started ends, and the terminal is not the window in front, ncode can tell you:
- a bell (
BEL), or a desktop notification through the terminal's OSC 9 support, or a macOS notification; - only while the terminal has reported that it lost focus (terminals that do not report focus never get a bell, so there are no false alarms);
- at most one bell every 2 seconds, so five approvals at once ring once.
Notifications (terminal.notify) is auto by default: OSC 9 in iTerm2, Ghostty and WezTerm, a bell elsewhere. bell, osc9 and os (the macOS notification centre) pick one way; off is silent. The texts are ncode: <project> needs you (approval) or (question), and ncode: <project> finished, failed or stopped.
The terminal's window or tab title follows the session: ncode · <project>, with · working while a run is live, · needs you while something waits for you, and · done after a turn that ended while you were away. ncode asks the terminal to put your old title back when it exits. terminal.title turns this off.
Copying#
y in select mode, and every other copy, goes to the macOS clipboard through pbcopy and says Copied N lines. Over SSH, or if pbcopy fails, ncode sends the text to the terminal as an OSC 52 request (through tmux's passthrough when inside tmux) and says Sent N lines to the terminal clipboard; if nothing arrived, your terminal does not allow OSC 52. The terminal clipboard takes at most 64 KiB; for more it says Not copied: the terminal clipboard takes at most 64 KiB.
Keyboard in your terminal#
- Redraw: Ctrl+L redraws the screen if the terminal left it garbled; it also heals itself on resize.
- Words: Option+← / → (also Ctrl+← / → and Alt+B / F) move by word in the composer.
- New line: Shift+Enter works in terminals that support the kitty keyboard protocol; elsewhere use Ctrl+O or Ctrl+J.
- Image paste: Ctrl+V attaches an image from the macOS clipboard (see Composer).
Vim keys#
NCODE_KEYMAP=vim, Vim mode in the Ctrl+P palette, or Keymap in Settings → Keys & input gives the composer vim's NORMAL and VISUAL modes. See the keyboard reference.
Layout#
In Settings → Layout & transcript:
| Setting | Default |
|---|---|
| Side panel | auto (hidden, or a one-line strip, until two or more agents work or something needs you) |
| Composer height | 3 rows |
| Show diffs | on (/diff on|off) |
| Diff lines shown | 12 |
| AI status lines | on |
| Notices stay for | 6 s |
| Status line items | mode, approval, model, effort, context, cost, waiting, vitals (terminal.status_items; branch adds the git branch and the number of changed files; vitals is the busiest model's tokens per second and the memory, shown while the side panel is not showing them) |
| Last turns printed on exit | 3 (terminal.exit_transcript, 0 to 20; 0 prints none) |
The editor Ctrl+X opens is $VISUAL, then $EDITOR, then vi; Editor for Ctrl-X in Settings → Keys & input overrides it.
Terminal.app and Alt#
- Nothing essential needs Alt, so a terminal where Option does not send Alt loses no essential action.
- In Terminal.app, select text with Option-drag while
/mouse onis set. - Ctrl+Shift+Z (redo) needs a terminal that reports Ctrl with Shift.