]` section. Only color fields are read — `label` and `dark` are inherited from the built-in:
```toml theme={null}
[themes.langchain]
primary = "#FF5500"
```
Omitted color fields retain the existing built-in values.
Changes to `[themes.*]` sections take effect on `/reload`.
### Map themes to terminals
If you switch between terminals with different color schemes (for example, a dark iTerm and a light Apple Terminal), map each one to a theme under `[ui.terminal_themes]`. Deep Agents Code matches the shell's `TERM_PROGRAM` and applies the mapped theme automatically:
```toml theme={null}
[ui.terminal_themes]
"Apple_Terminal" = "langchain-light"
"iTerm.app" = "langchain"
```
Press `T` in the `/theme` picker to save the highlighted theme for the current terminal, or run `echo $TERM_PROGRAM` to find your terminal's identifier and add it by hand.
#### Picker shortcuts
In the `/theme` selector:
* `N` toggles between display labels and canonical registry keys—the keys are what `[ui] theme` and `[ui.terminal_themes]` accept.
* `T` saves the highlighted theme into `[ui.terminal_themes]` for the current `TERM_PROGRAM`. The mapped theme is badged `(default)` in the picker.
#### Common `TERM_PROGRAM` values
Keys are matched verbatim against the environment variable—quote them in TOML when they contain dots or special characters.
| Terminal | `TERM_PROGRAM` |
| --------------------------- | ---------------- |
| Apple Terminal | `Apple_Terminal` |
| iTerm2 | `iTerm.app` |
| WezTerm | `WezTerm` |
| VS Code integrated terminal | `vscode` |
| Ghostty | `ghostty` |
#### Resolution order
Deep Agents Code resolves a theme on every launch using this precedence:
1. `DEEPAGENTS_CODE_THEME` environment variable (explicit override).
2. `[ui.terminal_themes]` mapping for the current `TERM_PROGRAM`.
3. `[ui] theme` saved preference (set by `/theme`).
4. The built-in default (`langchain`).
***
## Auto-update
Deep Agents Code automatically checks for and installs updates by default.
To opt out of automatic updates:
```toml theme={null}
[update]
auto_update = false
```
```bash theme={null}
export DEEPAGENTS_CODE_AUTO_UPDATE=0
```
The environment variable takes precedence over the config file.
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.
To suppress automatic update checks entirely:
```toml theme={null}
[update]
check = false
```
```bash theme={null}
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's 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.
***
## Uninstall
To remove the `dcode` and `deepagents-code` binaries and the isolated tool environment, run:
```bash theme={null}
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:
```bash theme={null}
rm -rf ~/.deepagents
```
***
## Managed deployments
The [install script](https://github.com/langchain-ai/deepagents/blob/main/libs/code/scripts/install.sh) 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. `chown`s 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:
```bash theme={null}
# Pin an exact version for reproducible installs across the fleet
curl -LsSf https://langch.in/dcode | DEEPAGENTS_CODE_VERSION="0.1.16" bash
```
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.
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`.
Comma-separated pip extras to install, e.g. `ollama`, `ollama,groq`, or `daytona`. See [`pyproject.toml`](https://github.com/langchain-ai/deepagents/blob/main/libs/code/pyproject.toml) for the available extras.
Python version to use for the install.
Set to `1` to skip optional tool checks.
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.
Path to the uv binary. Auto-detected if unset.
Auto-update is enabled by default for managed installs. To opt out, set `DEEPAGENTS_CODE_AUTO_UPDATE=0` in the user's shell profile or deploy a `config.toml` with `[update] auto_update = false` to `~/.deepagents/config.toml`. To suppress automatic updates and update checks entirely, set `DEEPAGENTS_CODE_NO_UPDATE_CHECK=1` or deploy `[update] check = false`.
To route every user's model traffic through a managed gateway (provisioning a gateway key and base URL fleet-wide), see [Managed gateways](#managed-gateways).
***
## Environment variable reference
All Deep Agents Code-specific environment variables use the `DEEPAGENTS_CODE_` prefix. See [`DEEPAGENTS_CODE_` prefix](#deepagents_code_-prefix) for how the prefix also works as an override for third-party credentials.
Toggle automatic Deep Agents Code updates. Enabled by default; set to `0`, `false`, `no`, or `off` to opt out.
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.
Path for the debug log file.
Colon-separated paths added to the [skill containment allowlist](#skill-directory-allowlist).
Override the LangSmith project name for Deep Agents Code's own agent traces. Shell commands still run with the user's original `LANGSMITH_PROJECT`, so app, test, or script traces can appear in a separate project. See [Trace with LangSmith](/oss/python/deepagents/code/overview#trace-with-langsmith).
A second LangSmith project to *also* write agent traces to. When set and tracing is active, each agent run is dual-written to the primary project (from `DEEPAGENTS_CODE_LANGSMITH_PROJECT`, or `deepagents-code` by default) and this project. Off by default. See [Dual-write traces to a second project](/oss/python/deepagents/code/overview#trace-with-langsmith).
Disable automatic update checking when set. This also prevents automatic update installs at startup.
Comma-separated shell commands to allow (or `recommended` / `all`).
Attach a user identifier to LangSmith trace metadata.
***
## External editor
Press `Ctrl+X` or type `/editor` to compose prompts in an external editor. Deep Agents Code checks `$VISUAL`, then `$EDITOR`, then falls back to `vi` (macOS/Linux) or `notepad` (Windows). GUI editors (VS Code, Cursor, Zed, Sublime Text, Windsurf) automatically receive a `--wait` flag so Deep Agents Code blocks until you close the file.
```bash theme={null}
# Set in your shell profile (~/.zshrc, ~/.bashrc, etc.)
export VISUAL="code" # GUI editor (--wait auto-injected)
export EDITOR="nvim" # Terminal fallback
```
***
## Hooks
Hooks let external programs react to Deep Agents Code lifecycle events. Configure commands in `~/.deepagents/hooks.json` and it pipes a JSON payload to each matching command's stdin whenever an event fires.
Hooks run fire-and-forget in a background thread — they never block Deep Agents Code and failures are logged without interrupting your session.
### Setup
Create `~/.deepagents/hooks.json`:
```json theme={null}
{
"hooks": [
{
"command": ["bash", "-c", "cat >> ~/deepagents-events.log"],
"events": ["session.start", "session.end"]
}
]
}
```
Now every time a session starts or ends, Deep Agents Code appends the event payload to `~/deepagents-events.log`.
### Hook configuration
The config file contains a single `hooks` array. Each entry has:
Command and arguments to run. No shell expansion: use `["bash", "-c", "..."]` if needed.
Event names to subscribe to. Omit or leave empty to receive **all** events.
```json theme={null}
{
"hooks": [
{
"command": ["python3", "my_handler.py"],
"events": ["session.start", "task.complete"]
},
{
"command": ["bash", "log_everything.sh"]
}
]
}
```
The second hook above has no `events` filter, so it receives every event Deep Agents Code emits.
### Payload format
Each hook command receives a JSON object on stdin with an `"event"` key plus event-specific fields:
```json theme={null}
{
"event": "session.start",
"thread_id": "abc123"
}
```
### Events reference
#### `session.start`
Fired when an agent session begins (both interactive and non-interactive modes).
The session thread identifier.
#### `session.end`
Fired when a session exits.
The session thread identifier.
#### `user.prompt`
Fired in interactive mode when the user submits a chat message.
No additional fields.
#### `input.required`
Fired when the agent requires human input (human-in-the-loop interrupt).
No additional fields.
#### `permission.request`
Fired before the approval dialog when one or more tool calls need user permission.
Names of the tools requesting approval.
#### `tool.error`
Fired when a tool call returns an error.
Names of the tool(s) that errored.
#### `task.complete`
Fired when the agent finishes its current task (the streaming loop ends without further interrupts).
The session thread identifier.
#### `context.compact`
Fired before Deep Agents Code compacts (summarizes) the conversation context.
No additional fields.
### Execution model
* **Background thread**: Hook subprocesses run in a thread via `asyncio.to_thread` so the main event loop is never blocked.
* **Concurrent dispatch**: When multiple hooks match an event, they run concurrently in a thread pool.
* **5-second timeout**: Each command has a 5-second timeout. Commands that exceed this are killed.
* **Fire-and-forget**: Errors are caught per-hook and logged at debug/warning level. A failing hook never crashes or stalls Deep Agents Code.
* **Lazy loading**: The config file is read once on the first event dispatch and cached for the rest of the session.
* **No shell expansion**: Commands are executed directly (not through a shell). Wrap in `["bash", "-c", "..."]` if you need shell features like pipes or variable expansion.
### Hook examples
```json theme={null}
{
"hooks": [
{
"command": ["bash", "-c", "jq -c . >> ~/.deepagents/hook-events.jsonl"],
"events": []
}
]
}
```
```json theme={null}
{
"hooks": [
{
"command": [
"bash", "-c",
"osascript -e 'display notification \"Agent finished\" with title \"Deep Agents\"'"
],
"events": ["task.complete"]
}
]
}
```
Write a handler script that reads the JSON payload from stdin:
```python title="my_handler.py" theme={null}
import json
import sys
payload = json.load(sys.stdin)
event = payload["event"]
if event == "session.start":
print(f"Session started: {payload['thread_id']}", file=sys.stderr)
elif event == "permission.request":
print(f"Approval needed for: {payload['tool_names']}", file=sys.stderr)
```
```json title="~/.deepagents/hooks.json" theme={null}
{
"hooks": [
{
"command": ["python3", "my_handler.py"],
"events": ["session.start", "permission.request"]
}
]
}
```
### Security considerations
Hooks follow the same trust model as Git hooks or shell aliases — any user who can write to `~/.deepagents/hooks.json` can execute arbitrary commands. This is by design:
* **No command injection**: Payload data flows only to stdin as JSON, never to command-line arguments. `json.dumps` handles escaping.
* **No shell by default**: Commands run with `shell=False`, preventing shell injection.
* **Malformed config**: Invalid JSON or unexpected types produce logged warnings, not security issues.
Only add hooks from sources you trust. A hook has the same permissions as your user account.
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/code/configuration.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).