3code - reference

Introduction

This is the reference half of the documentation: every config file option, every command-line switch, every interactive command, in one place. The manual explains how to get things done; this page tells you exactly what a key does and where it lives.

Command line switches

usage: 3code [options] [prompt...]
       3code good                   # list known-good provider/variant combos
       3code sandbox restrict DIR -- CMD   # run CMD sandboxed (alias: sb)
       3code setup                  # one-time elevated sandbox setup (Windows)

switcheffect
-m, --model PROVIDER[.MODEL]pick a model from the config, overriding [settings] current
-c, --config FILEread providers and settings from FILE for this run, instead of the default config path
-r, --resume[=ID]resume the latest session from this directory, or a specific one by ID (-r ID, -rID, -r=ID, -r:ID, --resume=ID; every value option takes these forms)
-i, --interactivedrop into the REPL after running an initial prompt; without it, a prompt argument runs once and exits
-l, --listlist recent sessions for this directory (max 20) and exit
-a, --allwith -l / -f: every directory, not just this one
-f, --find TERMS...search session transcripts for TERMS and exit (case-insensitive; a quoted arg is a phrase)
--page Nlater screenful of --list / --find results
-g, --goodlist known-good provider/variant combos and exit
-x, --experimentalallow combinations outside the known-good list
-p, --privateprivate mode: only allow-private providers/models run (see Private mode)
--no-sandboxdisable sandbox enforcement for this run (bash runs unconfined)
-D, --debugcolored debug trace to stderr
--acpspeak ACP v1 on stdio as the agent, for editors and custom clients (takes no prompt)
-v, --versionprint version (release builds carry branch/commit provenance)
-h, --helpthe usage message, including the config path

Subcommands: good (same as --good), sandbox / sb (run a command under the filesystem policy), setup and unsetup (Windows sandbox/network-wall install and removal, see network rules).

A prompt given as an argument runs one turn and exits (oneshot); -r continues the directory's latest session the same way. Exit codes: 0 for a completed turn, 2 usage, 3 config, 1 crash. See Scripting in the manual for the pattern and its parsing limitation.

Interactive commands

Everything typeable at the ❯ prompt. Tab completes commands, provider names, model names, and paths where supported.

commandeffect
:help / :?command and key list with current bindings
:tokenstoken usage for this session (input, cached, output, total)
:clearreset the conversation, keep provider and model
:modellist models for the current provider, * marks the current
:model Xswitch to model X within the current provider
:providerlist configured providers; the current one shows its model
:provider Xswitch to provider X
:provider addadd a provider (interactive wizard, verified)
:provider add Xsame, with X as name, URL, or API key
:provider edit Xedit provider X (url, key, models)
:provider update Xreplace provider X's model list (key and url unchanged)
:provider new [X]list models the provider serves that the config doesn't list yet (all providers when X is omitted)
:provider pull [X [M...]]append those models to X's list, or every provider's; specific models optional
:provider rm Xremove provider X
:reasoninglist reasoning levels for the current model, * marks active
:reasoning Xswitch reasoning level
:streamingshow streaming mode
:streaming on/offtoggle SSE streaming; off is the reliable fallback for flaky SSE
:verifiershow the goal-mode verifier (off = the session model checks)
:verifier listlist the verification-class models available to you
:verifier Xrun goal checks on X (a listed verifier, or any model of the current provider)
:verifier on/offtoggle the verifier without losing the selection
:notifyshow notify mode
:notify on/offtoggle the desktop notification that fires when a turn ends
:retryretry now: cut a retry backoff or resend a data-less in-flight request
:retry listshow patient-retry mode
:retry on/offtoggle patient retry of 429/5xx/network errors
:privateshow private mode and trusted providers
:private on/offtoggle private mode for this session (bar recolors)
:private allow X [M]trust provider X, optionally one model, with private data
:promptshow the active system prompt (compiled-in, or the file override if one matched)
:show [N]show the full output of tool call N (default: last)
:loglist all tool calls this session
:sessionslist recent sessions saved in this directory (max 20)
:sessionshow this session's ID (for --resume=ID)
:resumelist this directory's sessions; :resume ID swaps the running 3code onto that session
:summarizecollapse old turns into a synthetic recap
:versionshow the running 3code version
:sandbox / :sbshow the active filesystem sandbox rules
:sandbox on/offtoggle sandbox enforcement
:sandbox allow Tadd a writable/connectable rule
:sandbox readonly Padd a read-only rule
:sandbox deny Tadd a deny rule
:sandbox ask Pdeny P, but offer a one-key approval (f file / d dir / n no) when a sandboxed command is blocked on P
:sandbox editopen the policy file in $VISUAL/$EDITOR, reload on quit
:pluginslist loaded plugin libraries, hooks, call counts, registered tools
:plugin debug on/offtrace every plugin call to THREECODE_DEBUG_LOG (or stderr)
:! CMDrun a shell command yourself, output streamed live to scrollback only
:quit / :q / :exitleave

Key bindings

Default keys at the prompt. :help prints the ones in effect; rebinding keys covers how to change them.

keyaction
Entersubmit; on an empty prompt, continue the ongoing session (a turn runs with nothing appended)
Shift+Enter or Alt+Enterinsert a newline
Up / Downmove through visual rows, then history
Ctrl+Arrowmove by word
Cmd+Aselect all (kitty keyboard protocol terminals)
Ctrl+Udelete to start of line
Ctrl+Wdelete the previous word
Ctrl+Kdelete to end of line
Alt+D / Ctrl+Deletedelete the next word
Ctrl+Ttranspose characters around the cursor
Ctrl+K / Ctrl+Udelete to end / start of line (into the kill ring)
Ctrl+W / Alt+Ddelete previous / next word (into the kill ring)
Ctrl+Yyank the last kill
Alt+Ycycle older kills right after Ctrl+Y
Alt+.insert the last word of the previous history entry
Ctrl or Ctrl+/undo; a typed run retracts in one step
Alt+Rrevert to the recalled entry as recorded (empty draft at the prompt)
Alt+Ttranspose the words around the cursor
Alt+U / Alt+L / Alt+Cupcase / downcase / capitalize the next word
Ctrl+Qinsert the next key literally (a real tab, an escape byte)
Ctrl+]jump to the next occurrence of the next typed character
Ctrl+@ or Alt+Spaceset the mark (binds exchange-point-and-mark to swap back)
Ctrl+R / Ctrl+Sincremental history search: type to narrow, Ctrl+R/Ctrl+S step older/newer, Enter submits, Esc accepts, Ctrl+G aborts
Alt+P / Alt+Nhistory search completed at Enter
Alt+< / Alt+>jump to the oldest entry / back to the draft
Ctrl+Lclear the screen
Alt+Eedit the input buffer in $VISUAL/$EDITOR
Ctrl+X Ctrl+Esame (emacs edit-and-execute-command)
Ctrl+Cclear current input; cancel the turn when it is empty
Escsame as Ctrl+C
Ctrl+Dexit

Config file

Location: ~/.config/3code/config on Linux, ~/Library/Application Support/3code/config on macOS, %APPDATA%\3code\config on Windows; XDG_CONFIG_HOME overrides the base directory on every platform. -c FILE / --config FILE reads a different file for a single run; it is rewritten by 3code itself whenever providers or models change, same as the default. Annotated example: docs/config.example in the repository.

Values are Nim string literals, always wrapped in double quotes. parsecfg treats :, =, and # as syntax in unquoted values, so an unquoted URL or API key can silently truncate. ; and # start comments. An unknown section or key is a startup error with a file:line: pointer, so a typo cannot quietly disable a setting.

A minimal config:

[settings]
current = "baseten.glm5"

[provider]
name = "baseten"
url = "https://inference.baseten.co/v1"
key = "..."
models = "zai-org/GLM-5"

settings

Keys under [settings]:

keyvaluesmeaning
currentPROVIDER[.MODEL]the provider (and optional model) used at startup; -m overrides it, :provider/:model write it back
notifyon/off (default on)desktop notification when a turn ends; off on Termux
streamingon/off (default on)SSE streaming; off uses plain request/response, the reliable fallback for providers with flaky SSE
sandboxon/off (default on)filesystem sandbox enforcement; off also silences the Windows host-rules warning
patient_retryon/off (default on)long backoff for 429/5xx/network errors (see patient retry); patient-retry spelling accepted
sandbox_wall_warnon/off (default on)the Windows warning shown when host rules exist but 3code setup has not run
toneauto/dark/light (default auto)color palette selection; auto detects the terminal background via OSC 11. The legacy key mode and value bright still work
bash_pathfull pathWindows only: force a specific bash; auto-detection order is bash_path, PortableGit, Git for Windows, MSYS2, legacy msys64 tree
bashauto or full path (default auto)any OS: a full path overrides all detection; auto keeps the normal order
max_timeoutseconds (default 600)raises the ceiling the bash tool clamps every timeout request to; max-timeout spelling accepted, and THREECODE_MAX_TIMEOUT (below) wins for one run
browserfetchon/off (default off)when a plain web_fetch returns a JS shell (almost no text survives tag stripping), redo the fetch in a shared headless Chrome (one browser per machine on 127.0.0.1:9223, one tab per fetch) and return the rendered text
auto-updatetrue/falseself-update on launch; default on for prebuilt binaries, off for source builds. Nightly builds report branch and commit
verifier_modelPROVIDER.MODELthe model goal mode's satisfaction check runs on (see verifier models); a decision model answers typed questions in one request. Not set = the session model checks (the default)
verifieron/offenable/disable the selected verifier without clearing it; absent means on while a model is selected
allow-empty-prompton/off (default on)submitting an empty prompt continues the ongoing session: a turn runs on the messages as they stand, appending no user message; allow_empty_prompt spelling accepted

provider

One [provider] section per provider; repeat the section header for each. Sections may share a url and key; two sections with the same name are a config error.

keymeaning
nameprovider name, used in current and :provider
urlOpenAI-compatible base URL
keyAPI key (empty for auth = "oauth" subscription logins)
modelsspace-separated model IDs offered by :model
current_modelthe model :model last picked here; switching back to the provider returns to it. Written automatically
authoauth for browser-OAuth subscription logins (supergrok, chatgpt)
familyexperimental-only override that picks the system-prompt branch by family name, for combos off the known-good list. The same name drives the prompt-file override
model_prefixlegacy: prepended to bare models names; expanded on load, never written back

params

[params] sections override the known-good request parameters per (provider, model). provider scopes to one provider; model is optional: omit it (or leave it empty) and the entry covers every model of that provider. A model-scoped entry beats a provider-wide one; among equals the last section in the file wins. Unset keys keep the known-good value.

keyvaluesmeaning
temperaturefloatsampling temperature
max-tokensintper-turn output budget
think-backnone/turn/allhow much of the assistant's own reasoning_content is replayed in request history. none strips it everywhere (strict validators), turn keeps only the active tool loop, all keeps every turn (deepseek demands it; glm/kimi reward it)
context-windowint, tokensdrives compaction thresholds and the context gauge
allow-privatebooltrust this provider (or just this model) with private mode data; model-scoped beats provider-wide, false revokes

The [search] section configures the web_search tool.

keyvaluesmeaning
engineexa/parallel/brave (default exa)search backend. No automatic failover: the chosen engine is used as-is
exa-keystringExa paid tier (Exa runs keyless otherwise); also read from EXA_API_KEY
brave-keystringrequired for the brave engine; also read from BRAVE_API_KEY
keystringlegacy bare key, filed under the active engine

colors

Under [colors], the white-family colors respond to the light/dark tone; the colorful colors (cyan, green, red, magenta) are fixed in both tones.

keydefault (dark)default (light)meaning
bright-white\x1b[97m\x1b[30mprimary text: command help, :command tokens
off-white\x1b[38;5;252m\x1b[38;5;238mtool banners, prompt chrome
dim-white\x1b[38;5;244m\x1b[38;5;250msubtle FYI text
token-bar\x1b[36msamethe live token bar
private-bar\x1b[35msamethe bar while private mode is on

Values are quoted ANSI escape sequences; parsecfg interprets backslash escapes, so "\x1b[36m" becomes a real ESC byte. A plain key sets both tones; a -light suffixed key (bright-white-light) sets the light tone only and wins there.

shortcuts

[shortcuts] handles key rebinding for every editor command; see rebinding keys in the manual for the key-name grammar and the full command list. Values merge onto the defaults; an empty value unbinds a command.

plugins

The [plugins] section controls the native plugin tier (hooks and tools in dynamically loaded libraries); the keys are covered in detail in plugins.

keyeffect
disablecomma-separated plugin names (lib file stems) to skip at load
tools"on" advertises plugin-registered tools to the model (opt-in)
debug"on" traces every plugin call with mutation diffs
libextra plugin discovery directory, scanned before the defaults

Environment variables

variableeffect
XDG_CONFIG_HOMErelocates the config root: config file, user skills, global prompts
XDG_DATA_HOMErelocates the data root: sessions, history, auth tokens, builtin skills
THREECODE_MAX_TIMEOUTbash timeout ceiling for this run; wins over max_timeout
THREECODE_ALLOW_ROOTset to 1 to allow running as root (POSIX; refused otherwise)
THREECODE_PLUGIN_SYNC_MSsync-hook deadline override in ms (default 2000)
THREECODE_PLUGIN_TOOL_MSplugin tool-exec default timeout in ms (default 120000)

Both XDG variables work on every platform, including Windows, and expect absolute paths. They exist so tests and isolated setups can redirect all of 3code's state; the platform defaults apply when they are unset.

Diagnostics, useful when reporting a bug:

variableeffect
THREECODE_DEBUG_LOGappend the -D debug trace to this path (POSIX)
THREECODE_TRACE_FILEwrite startup timing milestones here (startup-trace builds)
THREECODE_TERMDBGarm terminal-model probes, logged to this path, for rendering bug reports
THREECODE_FORCE_SYNC_OUTPUTset to 1 to re-enable DEC 2026 synchronized repaints (off by default)

Variables starting with THREECODE_TEST_ belong to the test harness and change without notice.