LatentCodeCustomize
Configuration
Where LatentCode reads its settings from, how files combine, and every setting you can use.
Two files
| File | Holds |
|---|---|
| latentcode.json | How the agent behaves: models, agents, permissions, commands, MCP servers, plugins, instructions, compaction. |
| tui.json | How 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:
{
"$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"]
}{
"$schema": "https://latentstack.dev/tui.json",
"theme": "system",
"keybinds": { "session_new": "ctrl+x n,ctrl+n" }
}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:
| Order | Source |
|---|---|
| 1 | Global: ~/.config/latentcode/latentcode.json and latentcode.jsonc ($XDG_CONFIG_HOME/latentcode if you set it). |
| 2 | An extra file named by the LATENTCODE_CONFIG environment variable, if set. |
| 3 | Project: 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. |
| 4 | Settings 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 configtui.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:
| Folder | Contents | See |
|---|---|---|
| agents/ | Agent definitions, one Markdown file each | Agents |
| commands/ | Slash commands, one Markdown file each | Custom commands |
| skills/ | Skills, one folder with a SKILL.md each | Skills |
| plugins/ | Plugins, .ts or .js files | Plugins |
| tools/ | Custom tools | Custom tools |
| themes/ | Custom TUI themes as JSON | Themes |
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:
{
"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
| Key | Type | Description |
|---|---|---|
| model | string | Default model, as provider/model. See Models. |
| small_model | string | Model for background jobs such as session titles and goal checks. |
| default_agent | string | Primary agent new sessions start with. Default build. |
| agent | object | Configure built-in agents or add your own. See Agents. |
| subagent_depth | integer | How many levels deep subagents may start their own subagents. Default 1. |
Permissions and tools
| Key | Type | Description |
|---|---|---|
| permission | object | string | What needs approval. See Permissions. |
| tools | object | Legacy. {"bash": false} is turned into a deny permission. Prefer permission. |
| shell | string | Shell used for commands the agent runs and for ! commands. Default: $SHELL. |
| tool_output.max_lines | integer | Longer tool output is truncated and saved to a file the agent can read. Default 2000. |
| tool_output.max_bytes | integer | Same, in bytes. Default 51200. |
| attachment.image | object | Resizing for attached images: auto_resize (default true), max_width and max_height (default 2000). |
Context and instructions
| Key | Type | Description |
|---|---|---|
| instructions | string[] | Extra rule files, globs or URLs added to every session. See Rules. |
| compaction.auto | boolean | Summarize the conversation automatically when context runs low. Default true. |
| compaction.prune | boolean | Free context by dropping old tool output. Default true. |
| compaction.tail_turns | integer | Recent turns kept word for word when compacting. Default 2. |
| goal | object | maxTurns, maxDurationMinutes, maxTokens: limits for one goal run. See Goals. |
| snapshot | boolean | Record file snapshots so /undo can restore files. Default true. |
Extensions
| Key | Type | Description |
|---|---|---|
| command | object | Custom slash commands. See Custom commands. |
| skills | object | paths 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. |
| mcp | object | MCP servers. See MCP servers. |
| plugin | array | Plugins: npm package names or file paths. See Plugins. |
| formatter | boolean | object | Format files after the agent edits them. Off unless set: true turns on the built-in formatters; an object also adds or overrides formatters. |
| lsp | boolean | object | Language servers that give the agent diagnostics after edits. Off unless set: true turns on the built-in servers; an object configures them. |
Everything else
| Key | Type | Description |
|---|---|---|
| username | string | Name shown for your messages. Default: your OS user name. |
| autoupdate | boolean | "notify" | Global config only. false turns update checks off; "notify" tells you about updates without installing them. |
| debate.participantTimeoutMs | integer | Time limit for each /debate participant. Default 600000; 0 means no limit. |
theme and keybinds in tui.json, not latentcode.json.tui.json reference
| Key | Type | Description |
|---|---|---|
| theme | string | Color theme. Default latentcode; system follows your terminal's colors. See Themes. |
| keybinds | object | Change shortcuts. See Keybindings. |
| leader_timeout | integer | Milliseconds to wait for the next key after the leader key. Default 2000. |
| scroll_speed | number | Lines per scroll step. Default 3. |
| scroll_acceleration.enabled | boolean | Scroll faster the faster you scroll, like macOS. |
| diff_style | string | auto shows side-by-side diffs when the terminal is wide enough; stacked always shows one column. |
| mouse | boolean | Capture the mouse for clicking and scrolling. Default true. |
| cursor | object | style (block, underline, line or default; default block) and blinking (default true). |
| prompt.max_height | integer | Maximum height of the prompt box in lines. Default: a third of the terminal, at least 6. |
| attention | object | Desktop 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
| What | Where (macOS and Linux) |
|---|---|
| Config | ~/.config/latentcode |
| Sessions database | A 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.