ncode CLI / Configure
Settings reference
This reference is generated from the settings registry of ncode itself, so it lists exactly the keys that Settings shows and ncode config accepts.
How to read it:
- Key is the name for
ncode config get, set and reset, and for /settings <key>. - Scope is where the value is kept:
global (the database the desktop app shares), project (this project), session (one conversation), cli (cli.json, this terminal only) or project_file (.swarm_code/config.json, read-only here). - Applies says when a change takes effect, for example
at once, next turn, next spawn (the next agent started), next launch, or desktop when only the desktop app acts on it. - Override names a flag or environment variable that wins while it is set.
Scopes: global (the database, shared with the desktop app), project (the project row), session (this conversation), cli (cli.json, this terminal only), project_file (.swarm_code/config.json, read-only here).
Override: the environment variable or flag that wins over the stored value. The older SWARM_* name of each NCODE_* variable still works; when both are set, NCODE_* wins.
Models & effort#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
models.chat | Chat model | global | model | the first provider with a key | new conversations | — |
models.sub_agent | Sub-agent model | global | model | the first provider with a key | next spawn | — |
models.scheduled | Scheduled task model | global | model | the chat model | desktop | — |
models.workflow | Workflow model | global | model | the chat model | next turn | — |
models.implementer | Implementer model (consensus) | global | model | the planner implements | next turn | — |
efforts.default | Default effort | global | effort | medium | next turn | — |
efforts.sub_agent | Sub-agent effort | global | effort | medium | next spawn | — |
efforts.scheduled | Scheduled effort | global | effort | same as the default effort | desktop | — |
efforts.workflow | Workflow effort | global | effort | same as the default effort | next turn | — |
efforts.implementer | Implementer effort | global | effort | medium (not set) | next turn | — |
session.model | Model · this conversation | session | model | the chat model | next turn | --model |
session.effort | Effort · this conversation | session | effort | the default effort | next turn | — |
session.sub_agent_model | Sub-agent model · this conversation | session | model | the sub-agent model | next spawn | --model |
session.sub_agent_effort | Sub-agent effort · this conversation | session | effort | the sub-agent effort | next spawn | — |
session.mode | Mode | session | enum | build | next turn | — |
session.title | Title | session | text | New conversation | at once | — |
session.pinned | Pinned | session | toggle | off | at once | — |
session.consensus_checks | Consensus checks | session | checklist | the 7 defaults | next turn | — |
session.consensus_rounds | Consensus rounds | session | enum | 2 | next turn | — |
session.judge_model | Judge model | session | model | the sub-agent model | next turn | — |
session.judge_effort | Judge effort | session | effort | the default | next turn | — |
session.implementer_model | Implementer model · this conversation | session | model | the default implementer | next turn | — |
session.implementer_effort | Implementer effort · this conversation | session | effort | the default implementer effort | next turn | — |
Search & web#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
web.reader | Page reader for web_fetch | global | enum | web_fetch | next request | — |
Deep research#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
research.level | Default level | global | enum | medium | next research | — |
research.max_live | Agents in flight at once | global | integer | 10 | next research | — |
research.max_sources | Pages each agent must read | global | integer | 5 | next research | — |
research.recency_days | Only sources newer than | global | integer | any age | next research | — |
research.agent_timeout | Seconds an agent may take | global | duration | 10m | next research | — |
research.max_retries | Retries after a timeout | global | integer | 1 | next research | — |
research.retry_timeouts | Retry timed-out agents | global | toggle | on | next research | — |
research.headlines | A headline per round | global | toggle | on | next research | — |
research.auto_design | Designed HTML report | global | enum | deep | next research | — |
research.include_domains | Only these domains | global | list | | next research | — |
research.exclude_domains | Never these domains | global | list | | next research | — |
research.lead_model | Lead model | global | model | the sub-agent model | next research | — |
research.lead_effort | Lead effort | global | effort | default | next research | — |
research.worker_model | Worker model | global | model | the sub-agent model | next research | — |
research.worker_effort | Worker effort | global | effort | default | next research | — |
research.reporter_model | Reporter model | global | model | the sub-agent model | next research | — |
research.reporter_effort | Reporter effort | global | effort | default | next research | — |
Language servers#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
lsp.elixir | Elixir | global | lsp_command | built-in (elixir-ls --stdio) | new clients | — |
lsp.erlang | Erlang | global | lsp_command | no default | new clients | — |
lsp.typescript | TypeScript | global | lsp_command | built-in (typescript-language-server --stdio) | new clients | — |
lsp.javascript | JavaScript | global | lsp_command | built-in (typescript-language-server --stdio) | new clients | — |
lsp.python | Python | global | lsp_command | built-in (pyright-langserver --stdio) | new clients | — |
lsp.rust | Rust | global | lsp_command | built-in (rust-analyzer) | new clients | — |
lsp.go | Go | global | lsp_command | built-in (gopls serve) | new clients | — |
lsp.c | C | global | lsp_command | built-in (clangd --log=error) | new clients | — |
lsp.cpp | C++ | global | lsp_command | built-in (clangd --log=error) | new clients | — |
lsp.ruby | Ruby | global | lsp_command | built-in (solargraph stdio) | new clients | — |
lsp.java | Java | global | lsp_command | built-in (jdtls) | new clients | — |
lsp.swift | Swift | global | lsp_command | built-in (sourcekit-lsp) | new clients | — |
lsp.zig | Zig | global | lsp_command | built-in (zls) | new clients | — |
Agents & limits#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
limits.max_concurrent_agents | Max concurrent agents | global | integer | 4 | next spawn | — |
limits.max_agent_depth | Max agent depth | global | enum | 2 | next spawn | — |
limits.max_agent_turns | Max agent turns | global | integer | 60 | next spawn | — |
limits.sub_agent_timeout | Sub-agent time limit | global | duration | 30m | next spawn | — |
limits.workflow_budget | Workflow agent budget | global | integer | 128 | next turn | — |
limits.workflow_max_live | Max live workflow agents | global | integer | 16 | next turn | — |
limits.command_timeout | Command timeout | global | duration | 2m | next turn | — |
limits.tool_timeout | Tool timeout | global | duration | 2m | next request | — |
isolation.worktrees | Isolate sub-agents | global | toggle | on | next spawn | — |
isolation.backend | How to isolate | global | enum | auto | next spawn | — |
shell.env_scrub | Hide secrets from commands | global | toggle | on | next turn | — |
shell.env_keep | Keep these variables | global | list | GITHUB_TOKEN, GH_TOKEN | next turn | — |
shell.path | Shell | global | path | detect ($SHELL) | next turn | NCODE_SHELL or SWARM_CODE_SHELL |
shell.login | Login shell | global | toggle | on | next turn | — |
Approvals & trust#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
project.approval_mode | Approvals | project | enum | read_only | at once | — |
project.trusted | Trusted | project | toggle | off | at once | — |
project.allow | Always-allowed commands | project | list | | next turn | — |
project.name | Name | project | text | — | at once | — |
Project file#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
project_file.effort | effort | project_file | fact | — | at once | — |
project_file.swarm_effort | swarm_effort | project_file | fact | — | at once | — |
project_file.model | model | project_file | fact | — | at once | — |
project_file.swarm_model | swarm_model | project_file | fact | — | at once | — |
project_file.denied | Keys a project file may not set | project_file | fact | — | at once | — |
Appearance#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
terminal.theme | Theme | cli | enum | follow | at once | NCODE_THEME or SWARM_THEME |
terminal.colors | Colours | cli | enum | auto | next launch | NO_COLOR |
terminal.glyphs | Glyphs | cli | enum | auto | next launch | NCODE_ASCII or SWARM_ASCII |
terminal.ambiguous_width | Ambiguous-width characters | cli | enum | narrow | next launch | — |
terminal.reduced_motion | Reduced motion | cli | toggle | off | next launch | — |
terminal.accent | Accent colour | cli | color | Carbon (#FF6A1A) | next launch | — |
Layout & transcript#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
terminal.panel | Side panel | cli | enum | full | at once | — |
terminal.composer_rows | Composer height | cli | integer | 3 | at once | — |
terminal.inspector_width | Inspector width | cli | enum | default | at once | — |
terminal.show_diffs | Show diffs | cli | toggle | on | at once | — |
terminal.agent_summaries | AI status lines | cli | toggle | on | at once | — |
terminal.notice_seconds | Notices stay for | cli | duration | 6s | at once | — |
terminal.diff_lines | Diff lines shown | cli | integer | 12 | at once | — |
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
terminal.keymap | Keymap | cli | enum | standard | at once | NCODE_KEYMAP or SWARM_KEYMAP |
terminal.mouse | Wheel scrolling | cli | toggle | on | at once | NCODE_MOUSE or SWARM_MOUSE |
terminal.wheel_lines | Lines per notch | cli | integer | 3 | at once | — |
terminal.editor | Editor for Ctrl-X | cli | text | $VISUAL, then $EDITOR, then vi | at once | VISUAL, EDITOR |
terminal.hint_letters | Hint letters | cli | text | sfghjklwertuiop | at once | — |
terminal.keys | Key bindings | cli | keys | {} | at once | — |
Session & startup#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
terminal.startup_conversation | On launch | cli | enum | latest | next launch | NCODE_CONVERSATION or SWARM_CONVERSATION, --new/--continue/--resume |
terminal.companion | Visual companion | cli | toggle | on | next launch | NCODE_COMPANION or SWARM_COMPANION |
Storage#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
storage.retention_days | Automatically delete sessions older than | global | integer | off | desktop | — |
storage.prune_days | Prune agent details older than | global | integer | off | desktop | — |
Budget & usage#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
budget.monthly_usd | Monthly budget | global | money | no budget | at once | — |
Desktop app#
| Key | Label | Scope | Type | Default | Applies | Override |
|---|
desktop.theme | Theme | global | enum | carbon | desktop | — |
desktop.mode | Mode | global | enum | dark | desktop | — |
desktop.reduce_motion | Reduce motion | global | toggle | off | desktop | — |
desktop.bench_layout | Consensus card | global | enum | scales | desktop | — |
desktop.consensus_layout | Consensus panes | global | enum | stacked | desktop | — |
desktop.focus_on_finish | Bring the window to front when a run finishes | global | toggle | off | desktop | — |
desktop.show_global_tasks | Show global scheduled tasks | global | toggle | on | desktop | — |
desktop.show_reasoning | Expand activity & reasoning by default | global | toggle | off | desktop | — |
desktop.keys.file_finder | Key · File finder | global | combo | default (meta+p) | desktop | — |
desktop.keys.new | Key · New chat | global | combo | default (meta+n) | desktop | — |
desktop.keys.nudge_left | Key · Resize panes left | global | combo | default (shift+alt+ArrowLeft) | desktop | — |
desktop.keys.nudge_right | Key · Resize panes right | global | combo | default (shift+alt+ArrowRight) | desktop | — |
desktop.keys.quit | Key · Quit | global | combo | default (meta+q) | desktop | — |
desktop.keys.search | Key · Search | global | combo | default (meta+k) | desktop | — |
desktop.keys.settings | Key · Settings | global | combo | default (meta+,) | desktop | — |
desktop.keys.side | Key · Toggle side chat | global | combo | default (meta+shift+s) | desktop | — |
desktop.keys.sidebar | Key · Toggle panel | global | combo | default (meta+b) | desktop | — |
desktop.sidebar_collapsed | Sidebar hidden | global | toggle | off | desktop | — |
desktop.sidebar_width | Sidebar width (px) | global | integer | 280 | desktop | — |
desktop.sidebar_sections | Folded sidebar groups | global | map_readonly | {} | desktop | — |
desktop.sidebar_scroll | Sidebar scroll (px) | global | integer | 0 | desktop | — |
desktop.pane_view | Agents pane tab | global | enum | cards | desktop | — |
desktop.agents_view | Agents layout | global | enum | tree | desktop | — |
desktop.agents_density | Agent card density | global | enum | full | desktop | — |
desktop.side_w_2col | Side chat width, two columns (px) | global | integer | 440 | desktop | — |
desktop.side_w_3col | Side chat width, three columns (px) | global | integer | 380 | desktop | — |
desktop.pane_w | Agents pane width (px) | global | integer | 420 | desktop | — |
desktop.composer_h | Composer height (px) | global | integer | grows with the text | desktop | — |
desktop.side_composer_h | Side composer height (px) | global | integer | grows with the text | desktop | — |
desktop.prompt_size | Prompt drawer size | global | enum | md | desktop | — |