LatentCodeCustomize

Configuration

Where LatentCode reads its settings from, how files combine, and every setting you can use.

Two files

FileHolds
latentcode.jsonHow the agent behaves: models, agents, permissions, commands, MCP servers, plugins, instructions, compaction.
tui.jsonHow the terminal UI looks and responds: theme, keybindings, scrolling, notifications.

Both accept JSON with comments and trailing commas, so you can also name them .jsonc. Add the schema line to get completion and validation in your editor:

~/.config/latentcode/latentcode.jsonc
{
  "$schema": "https://latentstack.dev/config.json",
  "model": "latentrouter/bedrock-anthropic/anthropic/claude-sonnet-5",
  "small_model": "latentrouter/bedrock-anthropic/anthropic/claude-haiku-4-5",
  "permission": {
    "bash": { "git push*": "ask" }
  },
  "instructions": ["docs/CONVENTIONS.md"]
}
~/.config/latentcode/tui.json
{
  "$schema": "https://latentstack.dev/tui.json",
  "theme": "system",
  "keybinds": { "session_new": "ctrl+x n,ctrl+n" }
}
Note
Your gateway connection lives here too
latentcode config set … writes your gateway URL, API key and imported models into the global latentcode.jsonc. Use the command rather than editing those values by hand. See latentcode config.

Where config is read from

LatentCode merges every file it finds. Later sources override earlier ones, key by key:

OrderSource
1Global: ~/.config/latentcode/latentcode.json and latentcode.jsonc ($XDG_CONFIG_HOME/latentcode if you set it).
2An extra file named by the LATENTCODE_CONFIG environment variable, if set.
3Project: latentcode.json or latentcode.jsonc in the current directory and every parent up to the git root, and in project .latentcode folders. The file closest to where you started wins.
4Settings your administrator enforces always win.

Objects merge deeply, so a project file only needs the keys it changes. Arrays replace each other, except instructions, which are combined. Run this to see the result:

$latentcode debug config

tui.json is found the same way: global first, then tui.json in the project and its parents, then .latentcode folders.

The .latentcode folder

Besides config, a .latentcode folder in your project (or ~/.config/latentcode for everything you do) can hold:

FolderContentsSee
agents/Agent definitions, one Markdown file eachAgents
commands/Slash commands, one Markdown file eachCustom commands
skills/Skills, one folder with a SKILL.md eachSkills
plugins/Plugins, .ts or .js filesPlugins
tools/Custom toolsCustom tools
themes/Custom TUI themes as JSONThemes

The singular names (agent/, command/, skill/, plugin/, tool/) work too. Commit the folder so your team shares it.

Variables

Any string value can pull in an environment variable or a file:

JSONC
{
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://tracker.example.com/mcp",
      "headers": { "Authorization": "Bearer {env:TRACKER_TOKEN}" }
    }
  },
  "agent": {
    "reviewer": { "prompt": "{file:./prompts/reviewer.md}" }
  }
}
  • {env:NAME} becomes the variable's value, or an empty string if it isn't set.
  • {file:path} becomes the file's contents. Paths are relative to the config file; ~/ is your home directory. A missing file is an error.

latentcode.json reference

Every key is optional. Unknown keys are ignored. Invalid JSON, or a value of the wrong type, stops LatentCode with an error that names the file.

Models and agents

KeyTypeDescription
modelstringDefault model, as provider/model. See Models.
small_modelstringModel for background jobs such as session titles and goal checks.
default_agentstringPrimary agent new sessions start with. Default build.
agentobjectConfigure built-in agents or add your own. See Agents.
subagent_depthintegerHow many levels deep subagents may start their own subagents. Default 1.

Permissions and tools

KeyTypeDescription
permissionobject | stringWhat needs approval. See Permissions.
toolsobjectLegacy. {"bash": false} is turned into a deny permission. Prefer permission.
shellstringShell used for commands the agent runs and for ! commands. Default: $SHELL.
tool_output.max_linesintegerLonger tool output is truncated and saved to a file the agent can read. Default 2000.
tool_output.max_bytesintegerSame, in bytes. Default 51200.
attachment.imageobjectResizing for attached images: auto_resize (default true), max_width and max_height (default 2000).

Context and instructions

KeyTypeDescription
instructionsstring[]Extra rule files, globs or URLs added to every session. See Rules.
compaction.autobooleanSummarize the conversation automatically when context runs low. Default true.
compaction.prunebooleanFree context by dropping old tool output. Default true.
compaction.tail_turnsintegerRecent turns kept word for word when compacting. Default 2.
goalobjectmaxTurns, maxDurationMinutes, maxTokens: limits for one goal run. See Goals.
snapshotbooleanRecord file snapshots so /undo can restore files. Default true.

Extensions

KeyTypeDescription
commandobjectCustom slash commands. See Custom commands.
skillsobjectpaths and urls to load extra skills from. A urls entry is a URL, or { url, headerEnv } for a server that needs a key. See Skills.
mcpobjectMCP servers. See MCP servers.
pluginarrayPlugins: npm package names or file paths. See Plugins.
formatterboolean | objectFormat files after the agent edits them. Off unless set: true turns on the built-in formatters; an object also adds or overrides formatters.
lspboolean | objectLanguage servers that give the agent diagnostics after edits. Off unless set: true turns on the built-in servers; an object configures them.

Everything else

KeyTypeDescription
usernamestringName shown for your messages. Default: your OS user name.
autoupdateboolean | "notify"Global config only. false turns update checks off; "notify" tells you about updates without installing them.
debate.participantTimeoutMsintegerTime limit for each /debate participant. Default 600000; 0 means no limit.
Warning
theme and keybinds belong in tui.json
Put theme and keybinds in tui.json, not latentcode.json.

tui.json reference

KeyTypeDescription
themestringColor theme. Default latentcode; system follows your terminal's colors. See Themes.
keybindsobjectChange shortcuts. See Keybindings.
leader_timeoutintegerMilliseconds to wait for the next key after the leader key. Default 2000.
scroll_speednumberLines per scroll step. Default 3.
scroll_acceleration.enabledbooleanScroll faster the faster you scroll, like macOS.
diff_stylestringauto shows side-by-side diffs when the terminal is wide enough; stacked always shows one column.
mousebooleanCapture the mouse for clicking and scrolling. Default true.
cursorobjectstyle (block, underline, line or default; default block) and blinking (default true).
prompt.max_heightintegerMaximum height of the prompt box in lines. Default: a third of the terminal, at least 6.
attentionobjectDesktop notifications and sounds when LatentCode needs you. Off by default; set enabled: true. Also notifications, sound, volume (0–1, default 0.4) and sounds for custom sound files per event: default, question, permission, error, done, subagent_done.

Files LatentCode keeps

WhatWhere (macOS and Linux)
Config~/.config/latentcode
Sessions databaseA local database (latentcode db path prints where)
Logs~/.local/share/latentcode/log
Cache~/.cache/latentcode
State~/.local/state/latentcode

The XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME and XDG_STATE_HOME variables move these. latentcode debug paths prints the exact paths on your machine, including Windows.