Configuration

Empryo reads settings from two JSON files. Settings in the project file override the global file.

You rarely need to edit these files by hand. Most settings have a slash command, a panel under /settings, or a switch in the desktop app's Settings. In the terminal app, /settings → All settings lists every setting the terminal reads, with its value and where that value comes from: the project, your global config or the default. Type to search, then press Enter to change it for this project or globally, or to clear it.

If a file has a key Empryo does not know, the app tells you right away: which key, which file, and the nearest real setting when the key looks like a typo. That covers the fields inside each settings block too, so "compaction": { "keepRecnt": 4 } is reported with keepRecent as the fix. A dotted key such as "compaction.gapFill": "off" is reported too, because a dot does not nest settings: write "compaction": { "gapFill": "off" }. Unknown keys are ignored and left in the file. Keys an older version of Empryo wrote and no longer uses, such as fff or presentation, are dropped without a notice.

Ask Empryo to change a settingLink to this section

You can also ask in the chat: "use adaptive thinking", "make the diffs compact", or "turn provider search off in this project". The agent uses its settings tool to make the change.

The change takes effect in the running app, just as if you had used the Settings panel. The desktop app and the terminal app redraw right away. In a headless run the change is saved for the next run.

A few settings are only read at startup: instruction files, live translations, live skills, the Neovim binary and config, language-server auto-install, and telemetry. For those, the agent tells you to restart (/restart in the terminal, or quit and reopen the desktop app). Appearance settings for the desktop app can only be changed from a running desktop window.

Say "globally" to write ~/.empryo/config.json, or "for this project" to write .empryo/config.json. If you do not say, Empryo writes to the project file only when that file already sets the key. Otherwise it writes to the global file. It also removes any copy in the other file that would override your change.

The settings tool never handles credentials. Use /login, /keys, or empryo --set-key for those.

ExampleLink to this section

{
  "defaultModel": "anthropic/claude-sonnet-4-5",
  "thinking": { "mode": "adaptive" },
  "genome": true,
  "semanticSummaries": "ast",
  "diffStyle": "default",
  "chatLayout": "speakers",
  "scrollSpeed": 1,
  "toolTimeout": 2,
  "compaction": {
    "strategy": "auto",
    "triggerThreshold": 0.95,
    "keepRecent": 4
  },
  "taskRouter": {
    "spark":   "anthropic/claude-haiku-4-5",
    "ember":   "anthropic/claude-sonnet-4-5",
    "compact": "google/gemini-2.5-flash"
  },
  "agentFeatures": {
    "desloppify": true
  },
  "retry": { "maxTransientRetries": 5, "baseDelayMs": 3000 }
}

FieldsLink to this section

ModelLink to this section

DisplayLink to this section

| showReasoning | true | Show the model's reasoning. | | showNarration | | Show the model's short notes between tool calls. /narration sets it. | | motion | true | Animations. Turn off if you prefer no motion or work over a slow SSH connection. | | gitDecorations | true | Git status colors and letters in the file tree. | | vimHints | true | Show Vim key hints in the editor panel. | | nerdFont | auto | Use Nerd Font icons. Detected from your installed fonts. Set true or false to force it. | | editorSplit | 60 | Width of the editor panel, as a percentage. | | tabNaming | true | Name each tab from its first prompt. | | notifyTurns | | Notify you when a reply finishes while you are looking elsewhere. |

BehaviorLink to this section

An approval prompt also offers to allow that kind of request for the rest of the session: page fetches, or work outside the project. That choice lasts until the tab closes and covers nothing else. A project file can set approvals only after you trust the repo with /trust.

Code intelligenceLink to this section

CompactionLink to this section

When a conversation gets long, Empryo summarizes older parts to make room. See compaction.

"compaction": {
  "strategy": "auto",
  "triggerThreshold": 0.95,
  "resetThreshold": 0.4,
  "keepRecent": 4,
  "maxToolResults": 30,
  "llmExtraction": true
}

Related fields:

RetriesLink to this section

For rate limits and temporary errors. The wait doubles after each attempt. See model fallback.

"retry": { "maxTransientRetries": 3, "maxStallRetries": 3, "baseDelayMs": 2000 }

The older retry.maxAttempts field still works as a default for both retry counts.

Web searchLink to this section

With nativeSearch on, a supported model searches in one step and returns its own sources. Your search then goes only to your model provider. Two things to know:

• The provider runs the search, so Empryo cannot ask you to approve each search. Turn nativeSearch off if you want every search to run on your machine, with a prompt.
• The provider's search tool adds about 2,200 input tokens to each request. They are cached, so the real cost is lower.

Provider-side search is on for Claude (direct and through the proxy), GPT through the proxy, and OpenRouter models that support it. Other models use the search services you have keys for, with DuckDuckGo as a free fallback. /web-search shows which one is in use. You can change both settings in /provider-settings or in the desktop app's provider settings.

Provider toolsLink to this section

Some tools are run by the model provider, not by Empryo. Whether a tool is available depends on the provider and model, so these settings allow a tool but cannot guarantee it. See provider tools.

To see what is available for a model:

empryo --capabilities anthropic/claude-opus-4-6

These settings are under General in /provider-settings and in the desktop app's provider options.

BrowserLink to this section

Agents and limitsLink to this section

Accounts and gatewaysLink to this section

Live updatesLink to this section

Empryo also stores some of its own state in the config file, such as onboardingComplete, configVersion, and flags ending in IntroSeen. These are not settings. Changing them only shows or hides a one-time notice.

Task routerLink to this section

Use a different model for each kind of work. See use multiple models for advice.

"taskRouter": {
  "spark":      "anthropic/claude-haiku-4-5",
  "ember":      "anthropic/claude-sonnet-4-5",
  "webSearch":  "anthropic/claude-haiku-4-5",
  "desloppify": "anthropic/claude-haiku-4-5",
  "verify":     "anthropic/claude-haiku-4-5",
  "compact":    "google/gemini-2.5-flash",
  "semantic":   "anthropic/claude-haiku-4-5",
  "default":    null
}

If a slot is empty, Empryo uses default, then the model you are chatting with. taskRouter.maxConcurrentAgents is the single limit for dispatched and background agents together (default 16, 0 for no limit). There is no separate CPU or memory cap. Change it in desktop Settings → Agent → Routing → Parallel agents, or terminal /router → Concurrency. It applies live to agents already waiting.

Agent featuresLink to this section

"agentFeatures": {
  "marionette": false,
  "desloppify": true
}

Change these with /agent-features, or in the desktop app under Settings.

Tool loadingLink to this section

"agentFeatures": { "toolLoading": "auto" }

Every tool sent to the model adds to the size of each request. To keep requests small, Empryo holds back tools you use less often. The agent finds a held-back tool with tool_search and runs it with run_tool. The list of tools does not change during a conversation, which keeps the provider's prompt cache working. See tools.

Tools from MCP servers are always reached through run_tool. When a server connects or disconnects mid-conversation, the agent is told in a note. /tools shows which tools are sent and which are held back for the current model.

Python kernelLink to this section

"agentFeatures": { "pythonKernel": true }

This adds a python_kernel tool: a Python session that keeps its variables between calls. The agent can load a data file once and ask many questions about it, instead of starting a new python process each time. It uses IPython if it is installed, and plain Python otherwise. There is one session per project, it starts in the project folder, and reset: true clears it. A call that runs past its time limit restarts the session.

It is off by default because it runs code with your permissions, like shell does. It needs python3 on your PATH. To turn it on for one run, set EMPRYO_PYTHON_KERNEL=1.

Marionette modeLink to this section

The Marionette is an experimental step that maps which files matter for a prompt before the agent starts. marionetteMode sets how hard it looks:

"marionetteMode": "fast"

Change it with /marionette none|fast|assist|deep, in Settings, or for one run with --marionette-mode. marionetteBudget limits steps and time for assist and deep.

ProvidersLink to this section

Add keys and custom providers on these pages:

• All providers: environment variables and --set-key commands.
• Custom providers: any OpenAI-compatible API.
• Copilot: use your GitHub Copilot subscription.

Extra request-body parametersLink to this section

Some provider features are turned on by a field in the request, not by a tool. For example, DashScope reads enable_search. extraBody adds your own JSON to every chat request for a provider or a model.

{
  "extraBody": {
    "proxy": { "enable_search": true },
    "proxy/gpt-5.6-luna": { "verbosity": "low" }
  }
}

Keys are a provider id or a full model id. When both match, the model's entry wins. Custom providers have their own extraBody field, which this map can override per model.

Your fields replace anything Empryo would have sent under the same name. If the provider rejects a field, the request fails. Embedding requests do not get these fields.

Auth & key storageLink to this section

Empryo stores keys in your system keychain when one is available, and in a protected file otherwise.

empryo --set-key <provider> <key> saves a key. empryo --list-providers shows which providers have one.

Several keys for one providerLink to this section

Run --set-key again with a different key and Empryo keeps both. When one account runs out of quota during a turn, Empryo switches to the next key and continues. When every key is used up, you see the provider's error.

A short rate limit waits and retries with the same key. Keys from environment variables are never rotated. This works for built-in and custom providers. /keys lists what is stored.

Lookup orderLink to this section

{ "keyPriority": "env" }

Use "app" if keys exported in your shell keep overriding the ones you saved.

Use a key for one launchLink to this section

Environment variables work in the terminal app too. Nothing is saved:

LLM_GATEWAY_API_KEY=sk-... empryo
ANTHROPIC_API_KEY=sk-ant-... empryo

There is no --key flag.

Remove a keyLink to this section

/keys lists every provider and lets you delete a key. You can also delete it from your keychain directly, for example on macOS: security delete-generic-password -a empryo -s anthropic-api-key.

Instruction filesLink to this section

Empryo can load project rules from the instruction files other AI tools use:

{ "instructionFiles": ["empryo", "claude", "cursorrules"] }

Each file is read from the project folder and from your home folder. If they disagree, the project file wins. Choose files with /instructions in the terminal app, or under Settings → Instruction files in the desktop app.

Load a file only for some modelsLink to this section

By default, every enabled file loads for every model. instructionRouting limits a file to certain models or agents:

{
  "instructionFiles": ["empryo", "claude", "codex"],
  "instructionRouting": {
    "claude": ["claude"],
    "codex": ["openai", "agent:reviewer"]
  }
}

With this setup, a Claude tab reads EMPRYO.md and CLAUDE.md, and a GPT tab reads EMPRYO.md and AGENTS.md. Switch a tab's model and the files change on the next message.

/instructions shows a for: row under each enabled file. Press Enter to cycle through Everyone, Claude, OpenAI, and Gemini, or type /instructions route <file> <all|claude|openai|google>. The desktop app has the same choice next to each switch. A file that is on but not for the current model is marked *not for this model*. Project settings override global ones.

PrivacyLink to this section

Stop the agent from reading certain files:

/privacy add .env
/privacy add secrets/**

Some files are always blocked, including .env, .pem files, credentials, id_rsa, .npmrc, .netrc, shadow, and passwd.

Trusting a repositoryLink to this section

A repository's own .empryo/config.json could try to start programs on your machine. So until you trust a repository, Empryo ignores its mcpServers, providers, presets, and extraBody settings, and its hook files. Safe settings such as theme, model, and instructions still apply.

Trust is stored on your machine, outside the repository, so a repository cannot trust itself.

Environment variablesLink to this section

MorphsLink to this section

Morphs are panels and boards you build in the desktop app. A morph can also give the agent rules and lookups, which Empryo calls its cells. These settings are read from your global config only, so a repository cannot loosen them. See Morphs.

A morph you hide from the agent on its card stays hidden, whatever reach says. A morph that reads files from your repository, connects to a live socket, or runs its own display code only works after you trust the repository.

HooksLink to this section

See hooks. Empryo reads hooks from five places: Claude Code's three settings files and Empryo's two config files. Every matching hook runs.

StorageLink to this section

/storage shows how much disk space each part of Empryo uses (Genome, sessions, plans, memory, input history, binaries, fonts) and lets you clean it up.

Which setting winsLink to this section

Session, then project, then global. A command saves to whichever scope it targets. Use /model-scope to save the current model for the project or for everywhere.