]` section. Only color fields are read — `label` and `dark` are inherited from the built-in:
```toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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 can automatically check for and install updates.
```toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[update]
auto_update = true
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export DEEPAGENTS_CODE_AUTO_UPDATE=1
```
The environment variable takes precedence over the config file.
When enabled, Deep Agents Code checks PyPI for a newer version at session start and automatically upgrades using the detected install method (uv, Homebrew, or pip). When disabled (default), Deep Agents Code shows an update hint with the appropriate install command instead.
You can also check for and install updates manually at any time with the `/update` slash command, which bypasses the cache 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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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.
To pre-configure auto-update for managed installs, set `DEEPAGENTS_CODE_AUTO_UPDATE=1` in the user's shell profile or deploy a `config.toml` with `[update] auto_update = true` to `~/.deepagents/config.toml`. To suppress automatic updates and update checks entirely, set `DEEPAGENTS_CODE_NO_UPDATE_CHECK=1`.
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.
Enable automatic Deep Agents Code updates (`1`, `true`, or `yes`).
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 agent traces. See [Trace with LangSmith](/oss/python/deepagents/code/overview#trace-with-langsmith).
Disable automatic update checking when set.
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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"hooks": [
{
"command": ["bash", "-c", "jq -c . >> ~/.deepagents/hook-events.jsonl"],
"events": []
}
]
}
```
```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"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).