Skip to content

Configuration

Most settings can be changed in Settings in Desktop and Web, with /model, /permissions and other commands in the TUI, or with deepcode provider on the command line. This page lists the settings that live only in the configuration file or in environment variables.

DeepCode reads two JSON files and merges them:

LayerFileNotes
User~/.deepcode/deepcode_config.jsonCreated by deepcode init. Set DEEPCODE_HOME to move the whole directory.
Projectdeepcode_config.json in the project, or the nearest parent folder that has oneOverrides the user file key by key.

A project file cannot change what belongs to you: it cannot set provider endpoints, headers or named connections, the dictation endpoint, Full access, or turn the command sandbox off. Those keys are ignored when they appear in a project file.

deepcode init writes a user file that sets the default access to Ask:

{
"security": {
"accessPreset": "ask"
}
}

Model connections and their keys are managed with deepcode provider or in Settings → AI providers; see Models and providers. Keys are kept in ~/.deepcode/credentials.json, not in deepcode_config.json.

KeyValues (default)What it does
security.accessPresetask, read_only, full_accessTool access for new Turns. See Security and data.
security.permissionsobject ({})Per-tool rules, see below.
agents.defaults.connection / agents.defaults.modelconnection id / model idDefault connection and model for new Sessions.
agents.defaults.reasoningEfforta level the model supportsDefault reasoning effort.
agents.defaults.defaultPresetpreset idAgent preset for new Sessions.
agents.defaults.microcompacttrue / false (false)When a long Session nears its context limit, replace stale tool results with a short placeholder (keeping paths to saved output) before asking the model for a summary.
goal.completionVerifier"off" / "rule" / "reviewer" ("off")With "rule", a claim that a Goal is complete is turned back while the latest check failed or no work was done. "reviewer" adds an independent review: a second agent reads the changes and re-runs the checks before the Goal is recorded complete. A Goal’s confirmed checks run in every mode. Also in Desktop under Settings → General → Goal completion checks. See Goals.
goal.maxRejectionsinteger ≥ 1 (3)After this many rejected completion claims in a row with no file changes in between, the Goal is marked blocked (and after 10 rejected claims in all).
providers.egressobjectLimits which hosts receive model requests; see below.
mcpServersobjectMCP servers for the agent. See the MCP guide.
skills.disabledlist of Skill idsSkills that are not offered to the agent.
dictationobject (absent = off)Voice input. See Voice dictation.

security.permissions maps a tool name to rules of the form pattern: action, where the action is allow, ask, or deny. Tool names and patterns use shell-style wildcards; the pattern is matched against the command line or the target path. A plain string applies to every call of that tool.

{
"security": {
"permissions": {
"bash": { "git push*": "deny", "npm test*": "allow" },
"web_fetch": "ask"
}
}
}

A deny rule applies under every access preset, including Full access.

providers.egress restricts the hosts that receive prompts and tool results:

{
"providers": {
"egress": {
"allowedDomains": ["api.deepseek.com"],
"blockedDomains": [],
"mode": "enforce"
}
}
}

An empty allowedDomains list allows every host that is not blocked. A blocked domain always wins. mode is enforce (default) or warn, which only logs. The environment variables DEEPCODE_EGRESS_ALLOW_DOMAINS, DEEPCODE_EGRESS_BLOCK_DOMAINS (comma-separated) and DEEPCODE_EGRESS_MODE add to these settings. This setting is ignored in a project file.

An agent preset is a Markdown file with YAML front matter. The body is added to the system prompt; the file name is the preset id. DeepCode looks for presets in these folders, nearest first:

  1. <project>/.agents/presets/ and <project>/.claude/agents/
  2. ~/.deepcode/agent-presets/, ~/.agents/presets/ and ~/.claude/agents/
  3. The presets that ship with DeepCode (minimal, code-reader)
---
name: Reviewer
description: Reads and comments; never edits.
disallowed-tools: write, edit, multi_edit
allow-spawn: false
---
Review the change for correctness and explain each finding.
KeyMeaning
name, descriptionShown in the preset picker.
toolsAllow list of tools. Absent or * means all tools.
disallowed-toolsTools to remove. Also accepted as disallowedTools. Removing write, edit or multi_edit also removes apply_patch. * and rules such as Bash(rm:*) are rejected.
prompt-modeappend (default) or replace the base system prompt.
allow-spawnWhether the Session may start sub-agents.
modelSuggested model.
orderPosition in the picker.

Pick a preset with /preset in the TUI or the preset picker in Desktop and Web. A preset is fixed when the Session is created; editing the file later does not change existing Sessions. Presets do not change the access preset or the model route.

VariableDefaultEffect
DEEPCODE_HOME~/.deepcodeWhere configuration, credentials, Sessions, state and logs live.
DEEPCODE_SESSIONS_DIR$DEEPCODE_HOME/sessionsWhere Session files are stored.
DEEPCODE_RISK_EVALUATORoff1 screens a tool call that would run without asking; a risky call asks for approval instead. Not used under Full access.
DEEPCODE_COMMAND_SCREENnot setstrict adds screens for piping downloads into a shell and for package installs from unusual indexes or with look-alike names. The destructive-command screen is always on.
DEEPCODE_ALLOW_REMOTE_SCRIPToff1 lets one deliberate run pass the download-into-shell screen.
DEEPCODE_BASH_SCRUB_ENVoff1 removes credential-like variables (names containing KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL or AUTH) from the environment of shell commands, hooks and code mode.
DEEPCODE_BASH_FULL_ENVoff1 gives shell commands the full environment, including the model keys DeepCode itself uses, which are otherwise removed.
DEEPCODE_KEYRINGoff1 also reads connection keys from the OS keychain (service name deepcode) when credentials.json has none. Needs the keyring Python package; DeepCode still writes keys only to credentials.json.
DEEPCODE_EGRESS_ALLOW_DOMAINS, DEEPCODE_EGRESS_BLOCK_DOMAINS, DEEPCODE_EGRESS_MODEnot setSee Model egress.
DEEPCODE_INSTRUCTION_EXCLUDESnot setComma-separated globs of instruction files not to load, for example code/CLAUDE.md,**/vendor/**.
DEEPCODE_COMPACTION_MEMORYon0 stops writing compaction summaries into the project memory note compactions.md.
DEEPCODE_LOG_LEVELINFO (TUI), WARNING (deepcode mcp serve)Log level for those two commands.

Provider keys can also come from the provider’s own variable, such as OPENROUTER_API_KEY or DEEPSEEK_API_KEY; deepcode provider list shows which connections are ready. A background service started at login does not read your shell profile, so set keys with deepcode provider set rather than only in the shell.