ncode

CLI docs Terminal, themes and mouse

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.

The four-agent swarm in the rich truecolor glyph tier: thin transcript rails and tree branches, fine tick-style swarm progress bars, one verification approval waiting, the full side panel, and auto approval mode.
The matching four-agent swarm in the Terminal.app-style measured glyph tier, with plainer tree connectors, wider rails and outlined progress cells, while the approval, agent rows, composer and auto status line keep the same layout.

Dark and light#

/theme dark and /theme light switch at once and are remembered. At launch the theme is chosen in this order:

  1. NCODE_THEME=dark or light, while it is set;
  2. the theme you chose with /theme (or in Settings → Appearance);
  3. the desktop app's light or dark mode;
  4. 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.

The matching four-agent swarm in ncode's light theme: a pale transcript and panel, coloured agent names, Verify changes waiting for approval, thin rich-tier rails and progress bars, $0.04 spent, and auto approval mode.

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_COLOR gives 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 #RRGGBB value.

These apply at the next launch.

The matching four-agent swarm with ASCII glyphs: S swarm marks, pipe and backtick tree connectors, hyphen progress bars and composer divider, one verification approval waiting, and the full side panel with auto approval mode.

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 on turns 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 off goes back to the default. NCODE_MOUSE=1 or 0 wins over both for the next launch, and the terminal.mouse setting 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:

SettingDefault
Side panelauto (hidden, or a one-line strip, until two or more agents work or something needs you)
Composer height3 rows
Show diffson (/diff on|off)
Diff lines shown12
AI status lineson
Notices stay for6 s
Status line itemsmode, 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 exit3 (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 on is set.
  • Ctrl+Shift+Z (redo) needs a terminal that reports Ctrl with Shift.