]` 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]`. The CLI 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
The CLI resolves a theme on every launch using this precedence:
1. `DEEPAGENTS_CLI_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
The CLI 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_CLI_AUTO_UPDATE=1
```
The environment variable takes precedence over the config file.
When enabled, the CLI checks PyPI for a newer version at session start and automatically upgrades using the detected install method (uv, Homebrew, or pip). When disabled (default), the CLI 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, the CLI 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.
***
## Managed deployments
The [install script](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/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_CLI_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_CLI_NO_UPDATE_CHECK=1`.
***
## CLI environment variable reference
All CLI-specific environment variables use the `DEEPAGENTS_CLI_` prefix. See [`DEEPAGENTS_CLI_` prefix](#deepagents_cli_-prefix) for how the prefix also works as an override for third-party credentials.
Enable automatic CLI 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](#skills-extra-allowed-directories).
Override the LangSmith project name for agent traces. See [Trace with LangSmith](/oss/javascript/deepagents/cli/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. The CLI 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 the CLI 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 CLI lifecycle events. Configure commands in `~/.deepagents/hooks.json` and the CLI 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 the CLI 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, the CLI 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 the CLI 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 the CLI 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 the CLI.
* **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/cli/configuration.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).