Configuration

Deep Agents Code stores user configuration in its profile directory, which defaults to ~/.deepagents/, and in project-level dotfiles. Administrators can enforce settings from a fixed system path with managed_config.toml. For the full directory tree, session storage, and skill paths, see Data locations.

The main config files are:

How settings resolve

Deep Agents Code uses tiered configuration. The precedence order depends on the setting type.

General options (interpreter limits, update settings, themes, and other config.toml keys) use the first available value in this order:

1. Administrator-owned managed_config.toml
2. DEEPAGENTS_CODE_-prefixed environment variable
3. Canonical environment variable (when applicable)
4. ~/.deepagents/config.toml
5. Built-in default

Use dcode config or dcode config get <key> to see the current value and where it comes from. See Inspect configuration.

Provider API keys use a separate order. See Key resolution order.

Dotenv files load at startup: the nearest project .env (walking up from the launch directory), then ~/.deepagents/.env. Shell exports always beat .env values. See Loading order and precedence.

Provider endpoints (base_url) resolve with their matching API key. See Endpoints, keys, and gateways.

Inspect configuration

The dcode config commands show the settings Deep Agents Code uses and where each value comes from, without starting a session. Use them to confirm that an administrator setting, environment variable, or config.toml setting is active.

Add --verbose to dcode config or dcode config get to show descriptions, defaults, and where each setting can be defined. Combine --verbose with --json to include accepted types and other reference details. All three commands accept --json for machine-readable output. For the full list of commands, see CLI reference.

Environment variables

In addition to shell exports, Deep Agents Code reads environment variables from dotenv files, so you can keep API keys out of your shell profile and avoid duplicating .env files across projects.

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

For provider keys specifically, see Provider credentials.

Loading order and precedence

At startup, Deep Agents Code reads the nearest project .env, found by searching the directory you launch from and walking up through its parents (the first .env found wins), then ~/.deepagents/.env as a global fallback for all projects. A project .env wins over the global one, and neither overrides a value already set in your shell.

To skip the project .env entirely (the global ~/.deepagents/.env still loads), set startup.read_project_dotenv.

[startup]
read_project_dotenv = false

export DEEPAGENTS_CODE_READ_PROJECT_DOTENV=0

The setting resolves from managed config, the environment variable, and the user config.toml. All of those are read before any project .env is applied, so a project .env cannot turn the toggle off (or back on) for itself.

Deep Agents Code ignores environment variables that could alter executable lookup, interpreter or shell startup, Git behavior, or trust settings when they come from dotenv files.

DEEPAGENTS_CODE_ prefix

All Deep Agents Code-specific environment variables use a DEEPAGENTS_CODE_ prefix (e.g., DEEPAGENTS_CODE_AUTO_UPDATE, DEEPAGENTS_CODE_DEBUG). See the environment variable reference for the full list.

The prefix also works as an override mechanism for any environment variable Deep Agents Code reads, including third-party credentials. Deep Agents Code checks DEEPAGENTS_CODE_{NAME} first, then falls back to {NAME}:

# Give Deep Agents Code its own value, without affecting other tools
DEEPAGENTS_CODE_OPENAI_API_KEY=sk-cli-only

# Or set it empty so Deep Agents Code ignores a key exported in your shell
DEEPAGENTS_CODE_ANTHROPIC_API_KEY=

Skill directory allowlist

By default, when Deep Agents Code loads skills it validates that a resolved skill file path stays inside one of the standard skill directories. This prevents symlinks inside skill directories from reading arbitrary files outside those roots.

If you store shared skill assets in a non-standard location and use symlinks from a standard skill directory to reference them, you can add that location to the containment allowlist. This does not add a new skill discovery location: skills are still only discovered from the standard directories.

extra_allowed_dirs string[]

Paths added to the skill containment allowlist. Supports ~ expansion.

[skills]
extra_allowed_dirs = [
    "~/shared-skills",
    "/opt/team-skills",
]

Alternatively, set the DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS environment variable as a colon-separated list:

export DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS="~/shared-skills:/opt/team-skills"

When the environment variable is set, it takes precedence over the config file value. Changes take effect on /reload.

Profile location (DEEPAGENTS_HOME)

DEEPAGENTS_HOME selects the directory Deep Agents Code uses as its user profile — everything normally stored under ~/.deepagents/ moves under the configured path. This includes config.toml, the global .env, ~/.deepagents/.mcp.json and hooks.json, extensions/, per-agent directories (AGENTS.md, skills/, memories/, agents/), plugins, and .state/ (sessions, input history, credentials, and locks). When unset, the profile defaults to ~/.deepagents.

Valid forms are an absolute path or a path beginning with ~/:

export DEEPAGENTS_HOME="~/profiles/work"        # resolved against your home directory
export DEEPAGENTS_HOME="/opt/dcode-profiles/work"  # absolute; works even with no resolvable home

Relative paths and ~user forms are rejected. The resolved path must also not be the filesystem root, the home directory itself, an existing non-directory, an unreadable or unsearchable directory, or a symlink with a missing target — these fail at launch with an error.

The alias ~/.agents/skills/ (shared across AI CLI tools) is resolved from the launch home directory, not from DEEPAGENTS_HOME. See Data locations for the full directory tree.

Themes

Use /theme to open an interactive theme selector. Navigate the list to preview themes in real-time, press Enter to persist your choice to config.toml.

Deep Agents Code ships with many built-in themes. The default theme is langchain, a dark theme with LangChain-branded colors. The selected theme is persisted under [ui]:

[ui]
theme = "langchain-dark"

For user-defined themes, built-in overrides, and terminal-specific mappings, see the [themes.*] and [ui.terminal_themes] sections in Config file or configure them directly in config.toml:

[themes.my-solarized]
label = "My Solarized"
dark = true
primary = "#268BD2"
warning = "#B58900"

# Theme names with spaces require TOML quoting
[themes."ocean breeze"]
label = "Ocean Breeze"
primary = "#0077B6"
background = "#CAF0F8"

[themes.langchain]
primary = "#FF5500"

[ui.terminal_themes]
"Apple_Terminal" = "langchain-light"
"iTerm.app" = "langchain"

Auto-update

Deep Agents Code automatically checks for and installs updates by default.

To opt out of automatic updates:

[update]
auto_update = false

export DEEPAGENTS_CODE_AUTO_UPDATE=0

The environment variable takes precedence over the config file. Setting the environment variable to an empty value disables the feature.

When enabled (default), Deep Agents Code checks PyPI for a newer version at session start and automatically upgrades. When disabled, Deep Agents Code shows an update hint with the appropriate install command instead.

Pricing catalog auto-update

Deep Agents Code refreshes its model pricing catalog from upstream hourly in the background so cost estimates stay current. To opt out:

[update]
prices_auto_update = false

export DEEPAGENTS_CODE_PRICES_AUTO_UPDATE=0

Custom pricing overrides

For models that the catalog does not cover, add rates to ~/.deepagents/prices.json. The file uses the genai-prices provider-array schema. For example:

[
  {
    "id": "my-provider",
    "name": "My provider",
    "api_pattern": "gateway\\.example\\.com",
    "models": [
      {
        "id": "my-model",
        "match": { "equals": "my-model" },
        "prices": { "input_mtok": 2.5, "output_mtok": 10.0 }
      }
    ]
  }
]

Rates are in USD per million tokens. Restart Deep Agents Code after editing the file. Custom rates apply only when the genai-prices catalog does not include the model.

To suppress automatic update checks entirely:

[update]
check = false

export DEEPAGENTS_CODE_NO_UPDATE_CHECK=1

Disabling update checks also prevents automatic update installs at startup.

You can still check for and install updates manually at any time with the /update slash command, which runs an on-demand check and reports success or failure inline.

After an upgrade, Deep Agents Code shows a "what is new" banner on the next launch with a link to the changelog.

At session exit, if a newer version was detected during the session, an update banner is displayed as a reminder.

Display options

These [ui] keys tune what the terminal UI shows.

Session usage stats

Deep Agents Code shows session usage statistics when a session ends (default on):

[ui]
show_usage_stats = false

export DEEPAGENTS_CODE_SHOW_USAGE_STATS=0

The environment variable takes precedence; setting it to an empty value also disables the stats.

Collapse large pastes

Large pastes into the chat input are collapsed into compact placeholders (default on). To keep the full pasted text visible:

[ui]
collapse_pastes = false

export DEEPAGENTS_CODE_COLLAPSE_PASTES=0

Automatic memory

Deep Agents Code automatically saves learnings to memory. To keep loading memory while stopping automatic saves, change the automatic memory setting:

[memory]
auto_save = false

export DEEPAGENTS_CODE_MEMORY_AUTO_SAVE=0

You can still save memories explicitly with /remember. The environment variable takes precedence over the config file.

Conversation history retention

Offloading a thread with /offload writes a markdown archive under ~/.deepagents/conversation_history/. A startup sweep deletes archives older than 30 days. The sweep only touches regular .md files directly inside the archive directory, never blocks startup, and logs and swallows filesystem errors.

Change the retention window, or disable cleanup with 0:

[history]
retention_days = 90   # 0 disables the sweep

export DEEPAGENTS_CODE_HISTORY_RETENTION_DAYS=90

The environment variable takes precedence over the config file. With a DEEPAGENTS_HOME profile, archives live under $DEEPAGENTS_HOME/conversation_history/.

Compact on resume

Resuming a thread restores its full context, so the next turn pays for it. When a resumed thread's context exceeds a threshold, Deep Agents Code offers to compact it before your next message; declining is free and /compact (or /offload) remains available. The default threshold is 400,000 tokens; set it to 0 to disable the offer:

[threads]
compact_on_resume_threshold = 200000

Uninstall

To remove the dcode and deepagents-code binaries and the isolated tool environment, run:

uv tool uninstall deepagents-code

The uninstall command does not remove user configuration or session data. Deep Agents Code stores those files under ~/.deepagents/, including config.toml, hooks.json, the global .env, and .state/ contents such as saved sessions and credentials. To delete that data as well, run:

rm -rf ~/.deepagents

Managed configuration

Managed configuration lets administrators control Deep Agents Code settings across a fleet. Deep Agents Code checks the administrator-owned managed_config.toml before user environment variables and config, so users cannot override settings defined there.

Locate the managed config file

Deep Agents Code looks for managed_config.toml in a fixed location on each operating system:

On Windows, Deep Agents Code finds ProgramData through the system registry, not the %ProgramData% environment variable. Environment variables cannot change the managed config location. If the registry is unavailable, Deep Agents Code checks C:\ProgramData\dcode\managed_config.toml. If that file is also missing, Deep Agents Code cannot determine whether an administrator configured a policy, so commands that use configuration stop instead of running without it.

Create a managed policy

Use the same TOML sections and keys as ~/.deepagents/config.toml. Run dcode config --verbose --json to see the available settings, their accepted types, and whether they can be set in a config file.

For example, the following policy pins Manual approval mode, removes YOLO from the Shift+Tab mode cycle, limits shell auto-approval, restricts model use, disables the JavaScript interpreter, and enables client-side LangSmith secret redaction:

[startup]
mode = "manual"
yolo_switcher = false

[shell]
allow_list = ["git", "make"]

[models]
allowed = ["acme:production", "openai:*"]

[interpreter]
enable_interpreter = false

[tracing]
langsmith_redact = true

Only administrators should have permission to edit this file. Deep Agents Code treats it as read-only. Users can still save preferences to config.toml, but administrator settings remain in effect until they are removed from managed_config.toml.

Restrict model use

Set [models].allowed to exact, case-sensitive provider:model specifications, or use provider:* to allow all discoverable models from one provider. The allowlist applies to launch defaults, --model, /model, saved defaults, Auto classifiers, rubric graders, and explicit local subagent models.

[models]
allowed = [
    "acme:production",
    "openai:*",
]
default = "acme:production"
auto_classifier = "openai:gpt-5.5"

If you omit allowed, users can select any model. An empty list blocks all models. If a user's list is invalid, Deep Agents Code blocks all models. If the administrator's list is invalid, Deep Agents Code blocks startup, reload, and other commands that use configuration. The administrator's list replaces the user's list rather than combining with it. The managed default, recent, and auto_classifier values must also appear in the administrator's allowlist.

Adding a model under [models.providers.<name>].models makes it available for selection but does not allow it automatically. Add the exact model or a provider wildcard to the allowlist. A wildcard covers only the models available for that provider. If no models are available, Deep Agents Code cannot choose a default. When Deep Agents Code can identify the provider for a bare model name entered in the interface, it converts the name to provider:model before checking the allowlist.

Load policy remotely

You can store the policy on a central server while keeping its location in the local managed_config.toml:

[managed_config]
source = "https://config.example.com/dcode-policy.toml"

When you configure a remote policy, the local file can contain only the [managed_config].source setting. Put the complete policy in the remote TOML file. Deep Agents Code does not combine remote and local policy settings, and the remote file cannot point to another source.

Validate a managed policy

Use the configuration and diagnostic commands after deploying or changing policy:

dcode config path
dcode config
dcode config get startup.mode
dcode doctor

dcode config path shows the managed file location and whether Deep Agents Code can read it. dcode config and dcode config get label settings from the file as managed config. dcode doctor lists parsing errors, invalid values, and the settings that need correction. For a remote policy, it also shows the local file and remote URL. If an update fails, it confirms whether the session continues to use the previous valid policy.

Fix an invalid policy

Deep Agents Code stops rather than run without required administrator settings when it cannot read or parse the managed file, cannot download the complete remote policy, or cannot safely apply the policy. Commands that use configuration exit with code 78. You can still run dcode config, dcode doctor, dcode auth path, and help commands to troubleshoot the problem.

If an update fails during a running session, Deep Agents Code continues to use the previous valid policy and reports the failure. A new process cannot start until it can load a valid policy.

Managed deployments

The install script supports running as root, targeting macOS MDM tools (Kandji, Jamf, etc.) that execute scripts in a minimal root environment.

When id -u is 0, the script:

1. Resolves the real console user's HOME (via /dev/console or a /Users directory scan)
2. chowns all created files back to the target user after each install step

Non-root installs are unaffected: all root-specific code paths short-circuit when not running as root.

Pin the install with environment variables

The install script reads environment variables that let you pin a version, select extras, and choose a Python version fleet-wide. Set them on the same line as the piped install:

# Pin an exact version for reproducible installs across the fleet
curl -LsSf https://langch.in/dcode | DEEPAGENTS_CODE_VERSION="0.1.16" bash

DEEPAGENTS_CODE_VERSION string

Exact package version to install, e.g. 0.1.0 (or a pre-release such as 0.1.0rc1). Mutually exclusive with DEEPAGENTS_CODE_PRERELEASE — setting both is an error, since an exact pin already selects a single version.

DEEPAGENTS_CODE_PRERELEASE string

uv pre-release strategy applied when resolving the latest version: disallow, allow, if-necessary, explicit, or if-necessary-or-explicit. Mutually exclusive with DEEPAGENTS_CODE_VERSION.

DEEPAGENTS_CODE_EXTRAS string

Comma-separated pip extras to install, e.g. ollama, ollama,groq, or daytona. See pyproject.toml for the available extras.

DEEPAGENTS_CODE_PYTHON string default: 3.13

Python version to use for the install.

DEEPAGENTS_CODE_SKIP_OPTIONAL string

Set to 1 to skip optional tool checks.

DEEPAGENTS_CODE_VERBOSE string

Set to 1 to show uv's raw stderr (timing lines, unfiltered package diff) and the quiet-by-default status lines (optional-tool checks, post-install footer). Useful when debugging an install.

UV_BIN string

Path to the uv binary. Auto-detected if unset.

Auto-update is enabled by default for managed installations. To control updates for every user, set [update] auto_update = false or [update] check = false in managed_config.toml. For other installations, use DEEPAGENTS_CODE_AUTO_UPDATE=0, DEEPAGENTS_CODE_NO_UPDATE_CHECK=1, or the corresponding settings in ~/.deepagents/config.toml.

To route every user's model traffic through a managed gateway (provisioning a gateway key and base URL fleet-wide), see Managed gateways.

Environment variable reference

All Deep Agents Code-specific environment variables use the DEEPAGENTS_CODE_ prefix. See DEEPAGENTS_CODE_ prefix for how the prefix also works as an override for third-party credentials.

DEEPAGENTS_CODE_AUTO_UPDATE string

Toggle automatic Deep Agents Code updates. Enabled by default; set to 0, false, no, or off (or an empty value) to opt out.

DEEPAGENTS_CODE_AUTO_CLASSIFIER_TIMEOUT integer

Time budget in seconds for the Auto mode classifier to review each batch of gated actions. Valid range: 1–300. Out-of-range or non-integer values fall back to the default (20). Consider selecting a faster classifier model before raising this value. Overrides [models].auto_classifier_timeout in config.toml. See Auto classifier timeout.

DEEPAGENTS_CODE_DEBUG string

Enable verbose debug logging to a file. Accepts 1, true, yes, on (case-insensitive) as enabled; 0, false, no, off, empty string, or unset disables it. When enabled, the per-session server log file is preserved on shutdown and its path is printed to stderr for triage.

DEEPAGENTS_CODE_EXPERIMENTAL string

Opt into experimental, unstable Deep Agents Code behavior. Set to 1 (or any truthy value) to enable experimental features.

DEEPAGENTS_CODE_EXTENSIONS string default: true

Enable or disable Python extension discovery for every source, including -e / --extension. Overrides [extensions].enabled in config.toml. DEEPAGENTS_CODE_EXPERIMENTAL=1 is still required.

DEEPAGENTS_CODE_EXTENSIONS_TRUST string default: "ask"

Set the default project extension trust policy to ask, always, or never. Overrides [extensions].trust in config.toml. Only use always when every project you open is trusted.

DEEPAGENTS_CODE_DEBUG_FILE string default: /tmp/deepagents_debug.log

Path for the debug log file.

DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS string

Comma-separated project MCP server names to always reject by name. Deep Agents Code combines these names with [mcp].disabled_project_servers; denies win over saved approvals and the --trust-project-mcp flag.

DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS string

Comma-separated project MCP server names to pre-approve by name for any project. This is a process-wide escape hatch: A different project, command change, or URL change under the same server name still matches. When set, this variable replaces saved approvals for the process. Prefer saved approvals from the project MCP prompt when possible.

DEEPAGENTS_CODE_COLLAPSE_PASTES string default: true

Collapse large chat-input pastes into compact placeholders. Set to a falsy value (or empty) to keep full pasted text visible. Overrides [ui].collapse_pastes. See Collapse large pastes.

DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS string

Colon-separated paths added to the skill containment allowlist.

DEEPAGENTS_CODE_FORKED_SUBAGENTS string default: true

Let the built-in general-purpose subagent inherit the parent conversation and system prompt. Set to 0, false, no, or off (or an empty value) to use isolated mode. Set this variable in your shell or global ~/.deepagents/.env; Deep Agents Code ignores it in project .env files because inheritance can include private parent state. See Continue the parent conversation.

DEEPAGENTS_CODE_HISTORY_RETENTION_DAYS integer default: 30

Days an offloaded conversation-history archive is kept before the startup sweep deletes it; 0 disables cleanup. Overrides [history].retention_days. See Conversation history retention.

DEEPAGENTS_CODE_LANGSMITH_PROJECT string

Select the agent environment for Deep Agents Code's own traces using its tracer_session_name. Shell commands still run with the user's original LANGSMITH_PROJECT, so traces from tests or scripts can go to a different agent environment. See Trace with LangSmith.

DEEPAGENTS_CODE_LANGSMITH_REDACT string default: true

Toggle client-side secret redaction for Deep Agents Code's LangSmith agent-trace inputs and outputs. Enabled by default. Accepts 1, true, yes, or on to enable redaction and 0, false, no, or off to disable it, case-insensitively. When redaction is enabled, tracing is disabled for that run if redaction cannot be configured. See Configure LangSmith trace redaction.

DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS string

A second agent environment to copy traces to. Create the destination agent before enabling replicas. Set this variable and DEEPAGENTS_CODE_LANGSMITH_PROJECT to the respective environments' tracer_session_name values. When tracing is active, each run is written to both destinations. Off by default. See Trace with LangSmith.

DEEPAGENTS_CODE_LANGSMITH_TRACING string

Set to false to disable LangSmith agent tracing. An explicit false overrides other tracing-enable flags, including LANGSMITH_TRACING=true. The --no-tracing flag sets this override for one launch. Local history and model-provider requests are unchanged. See Disable agent tracing.

DEEPAGENTS_CODE_MEMORY_AUTO_SAVE string default: true

Let the agent proactively save learnings to memory. Set to a falsy value (or empty) to keep loading memory while stopping unprompted auto-saving; explicit saves still work. Overrides [memory].auto_save. See Automatic memory.

DEEPAGENTS_CODE_MCP_TOOL_TIMEOUT number default: 120

Maximum duration of an MCP tool call, in seconds. Accepts values from 1 through 900 and overrides [mcp].tool_timeout in user config. Invalid values fall through to the next configuration source. A timeout does not guarantee server-side cancellation, so retries can duplicate work.

DEEPAGENTS_CODE_NO_UPDATE_CHECK string

Disable automatic update checking when set. This also prevents automatic update installs at startup.

DEEPAGENTS_HOME string

Select the user profile and trust root instead of the default ~/.deepagents. Accepts an absolute path or a path beginning with ~/; ~user forms and relative paths are rejected. Must be set in the inherited shell environment — no .env file may set it. See Profile location.

DEEPAGENTS_CODE_ONBOARDING string

Override the first-run onboarding flow. Set to a truthy value to force it open on every startup; set to a falsy value to suppress it entirely (useful for CI and provisioned machines). Leave unset for the default first-run behavior.

DEEPAGENTS_CODE_PRICES_AUTO_UPDATE string default: true

Refresh the model pricing catalog from upstream hourly in the background. Set to a falsy value (or empty) to opt out. Overrides [update].prices_auto_update. See Pricing catalog auto-update.

DEEPAGENTS_CODE_READ_PROJECT_DOTENV string default: true

Load the project .env (found walking up from the working directory) into the process environment. Set to a falsy value to skip an untrusted repository's file; the global ~/.deepagents/.env still loads. Overrides [startup].read_project_dotenv. See Loading order and precedence.

DEEPAGENTS_CODE_RECENT_THREADS integer default: 100

Maximum number of recent threads to load and display in thread lists and selectors. Values below 1 are clamped to 1, and non-integer values use the default. -n or --limit overrides this value for dcode threads list.

DEEPAGENTS_CODE_RECURSION_LIMIT integer

LangGraph graph step budget, which is the maximum number of node invocations the dcode agent graph may execute per turn. Invalid values log a warning and resolution continues to the next source. When unset, Deep Agents Code inherits LANGGRAPH_DEFAULT_RECURSION_LIMIT or leaves the limit to the LangGraph server. See Agent runtime limits.

LANGGRAPH_DEFAULT_RECURSION_LIMIT integer

Upstream LangGraph graph step budget inherited when no Deep Agents recursion-limit source wins. Set it in your shell or the global ~/.deepagents/.env. Deep Agents Code ignores it in a project .env because it bypasses the bounded runtime.recursion_limit resolver. See Agent runtime limits.

DEEPAGENTS_CODE_SHELL_ALLOW_LIST string

Comma-separated shell commands to allow (or recommended / all).

DEEPAGENTS_CODE_SHOW_REASONING string

Show provider-visible reasoning in the interactive transcript and on stderr in non-interactive mode. Defaults to on in interactive sessions and off in non-interactive mode. Set to 1 to show it or 0 to hide it in both modes. Overrides [ui].show_reasoning; --show-reasoning takes precedence for a single launch. See Show provider-visible reasoning.

DEEPAGENTS_CODE_SHOW_USAGE_STATS string default: true

Show session usage statistics when a session ends. Set to a falsy value (or empty) to hide them. Overrides [ui].show_usage_stats. See Session usage stats.

DEEPAGENTS_CODE_USER_ID string

Attach a user identifier to LangSmith trace metadata.

Run diagnostics with dcode doctor

Use dcode doctor when Deep Agents Code is not starting correctly, a provider or MCP server does not connect, tracing is misconfigured, or an install or update looks wrong. It runs diagnostics without launching a session and summarizes the current runtime state.

# Show diagnostics in the terminal
dcode doctor

Output:

  Diagnostics ✓
  ├ deepagents-code: 0.1.30
  ├ deepagents (SDK): 0.7.0
  ├ Commit hash: e4709c2
  ├ Python: 3.13.11
  ├ Platform: darwin-arm64
  ├ Install method: uv
  └ Path: /Users/naomi/.local/share/uv/tools/deepagents-code

  Updates ✓
  ├ Update checks: enabled
  ├ Auto-updates: enabled
  ├ Latest version: up to date
  └ Last checked: 21m ago

  Tracing ✓
  ├ Tracing: enabled
  ├ Credentials: configured
  ├ Project: shared-deepagents
  └ Endpoint: https://api.smith.langchain.com

  Configuration ✓
  ├ Data directory: /Users/naomi/.deepagents (exists)
  └ Config file: /Users/naomi/.deepagents/config.toml (exists)

  Tip: Run `dcode config` or `dcode config get <key>` to drill into config details.
       Run `dcode --version` (or `dcode -v`) for dependency versions.

Data locations

Deep Agents Code stores data in two directory hierarchies:

• ~/.deepagents/ — Deep Agents-specific data (agent memory, skills, sessions). Relocatable with DEEPAGENTS_HOME; the paths below are then rooted at that directory instead.
• ~/.agents/ — Tool-agnostic data (skills shared across AI CLI tools)

Directory structure

~/.deepagents/
├── .state/                  # Per-machine Deep Agents Code state (managed automatically)
│   ├── sessions.db          #   SQLite database for conversation checkpoints
│   ├── history.jsonl        #   Command input history
│   ├── chatgpt-auth.json    #   ChatGPT OAuth token for the openai_codex provider
│   ├── ...                  #   Other markers & credentials
├── extensions/              # User-wide Python extensions (experimental)
└── {agent}/                 # Per-agent directory (default: "agent")
    ├── AGENTS.md            # User customizations to agent instructions
    ├── skills/              # User-level skills
    │   └── {skill-name}/
    │       └── SKILL.md
    └── agents/              # Custom subagent definitions
        └── {subagent-name}/
            └── AGENTS.md

~/.agents/                   # Tool-agnostic alias (shared across AI CLIs)
└── skills/                  # Skills available to any compatible tool
    └── {skill-name}/
        └── SKILL.md

{project}/                   # Project-level (in git repo root)
├── AGENTS.md                # Project instructions (root-level)
└── .deepagents/
│   ├── AGENTS.md            # Project instructions (preferred location)
│   ├── extensions/          # Project Python extensions (requires trust; experimental)
│   ├── skills/              # Project-specific skills
│   │   └── {skill-name}/
│   │       └── SKILL.md
│   └── agents/              # Project-specific subagents
│       └── {subagent-name}/
│           └── AGENTS.md
└── .agents/                 # Tool-agnostic project skills
    └── skills/
        └── {skill-name}/
            └── SKILL.md

What goes where

Precedence rules

When the same item exists in multiple locations, higher precedence wins completely (no merging).

Skills

Precedence order (lowest to highest):

1. ~/.deepagents/{agent}/skills/ — User Deep Agents Code
2. ~/.agents/skills/ — User tool-agnostic
3. .deepagents/skills/ — Project Deep Agents Code
4. .agents/skills/ — Project tool-agnostic (highest)

When a skill is loaded, Deep Agents Code verifies that the resolved file path stays within one of these directories or a previously approved trust entry. Symlinks that resolve outside all trusted roots are rejected until you approve the target directory (interactive) or add it to [skills].extra_allowed_dirs (required for headless runs). See Invoke a skill mid-session.

Subagents

Precedence order (lowest to highest):

1. ~/.deepagents/{agent}/agents/ — User-level
2. .deepagents/agents/ — Project-level (highest)

Each subagent is an AGENTS.md file with YAML frontmatter (name, description, optional model) and a markdown body for the system prompt. See Use subagents in Deep Agents Code for the full format reference.

Instructions

All instruction sources are combined (not overridden):

1. Package base prompt (always loaded)
2. ~/.deepagents/{agent}/AGENTS.md (appended)
3. .deepagents/AGENTS.md (appended)
4. AGENTS.md at project root (appended)

.deepagents vs .agents

Cleaning up

See also

• Provider credentials
• Config file
• CLI reference
• Hooks
• Data locations
• MCP tools
• Python extensions