---
name: deepagents-cli
description: |
  Deep Agents CLI — the LangGraph-based terminal coding agent. Use this skill whenever the user mentions deepagents, deep agents, the deep agents CLI, terminal coding agent, LangGraph agent, or asks about agent memory, agent skills, AGENTS.md, coding assistants in the terminal, or building scripted/CI agent workflows.
  Covers: interactive and non-interactive sessions, 20+ LLM providers, model configuration, skills, persistent memory, sandboxed execution, subagents, streaming, and the Agent Client Protocol.
---

# Deep Agents CLI

Terminal coding agent with persistent memory, skills, sandboxed execution, and 20+ LLM providers. Built on LangGraph. See the [official overview](https://docs.langchain.com/oss/python/deepagents/overview) and [CLI guide](https://docs.langchain.com/oss/python/deepagents/cli/overview).

> **Routing:** This file covers quick start, core concepts, and common workflows. For deeper details, read the appropriate reference file: CLI flags and shortcuts → `references/cli-reference.md` | Models and providers → `references/providers.md` | Skills → `references/skills-system.md` | Memory → `references/memory-and-persistence.md` | Sandboxes → `references/sandboxes.md` | SDK/programmatic usage → `references/sdk-customization.md` | Automation/CI → `references/workflows.md` | Streaming → `references/streaming.md` | Editor integrations → `references/acp.md`

> **Note:** All official documentation content is included in the local reference files. Only fetch external URLs if the local content appears inaccurate or incomplete.

## Quick Start

```bash
# Interactive session (default agent, default model)
deepagents

# Interactive with specific agent and model
deepagents -a myagent -M anthropic:claude-sonnet-4-5

# Non-interactive one-shot task
deepagents -n "Summarize README.md"

# Non-interactive with shell access
deepagents -n "List Python files and count lines" --shell-allow-list ls,wc,find

# Resume last session
deepagents -r
```

## Core Concepts

### Agents = Isolated Personas

Each agent has its own memory, skills, and AGENTS.md context file (`default` agent shown; use `-a <name>` for named agents):

```
~/.deepagents/default/
├── AGENTS.md          # Always-loaded context (preferences, conventions)
├── memories/          # Auto-saved topic memories
└── skills/            # User-level skills
```

```bash
deepagents -a researcher      # Use "researcher" agent
deepagents -a coder           # Use "coder" agent
deepagents list               # List all agents
deepagents reset --agent NAME # Clear agent memory
```

### Memory vs Skills

| Aspect | Memory (AGENTS.md + memories/) | Skills (SKILL.md) |
|--------|-------------------------------|-------------------|
| Loading | Always injected at startup | On-demand via progressive disclosure |
| Purpose | Preferences, conventions | Task-specific workflows |
| Use when | Context is always relevant | Instructions are large or situational |

See [Memory & Persistence](references/memory-and-persistence.md) and [Skills System](references/skills-system.md) for details on each system.

### Two Operating Modes

| Mode | Command | Use Case |
|------|---------|----------|
| **Interactive** | `deepagents` | Exploration, conversation, complex tasks |
| **Non-interactive** | `deepagents -n "task"` | Automation, scripting, CI/CD |

## Interactive Mode

Launch the REPL with `deepagents`. Key controls (see [CLI Reference](references/cli-reference.md) for the complete list):

| Action | Key/Command |
|--------|-------------|
| Submit | `Enter` |
| Newline | `Shift+Enter`, `Ctrl+J`, `Alt+Enter`, or `Ctrl+Enter` |
| Expand/collapse tool output | `Ctrl+E` |
| Toggle auto-approve | `Shift+Tab` or `Ctrl+T` |
| Select all text | `Ctrl+A` |
| File autocomplete | `@filename` |
| Run shell command | `!git status` |
| Interrupt | `Escape` or `Ctrl+C` |
| Exit | `Ctrl+D` or `/quit` |

### Slash Commands

```
/model               # Interactive model selector
/model provider:name # Switch to specific model
/remember [context]  # Update memory and skills from conversation
/tokens              # Show token usage
/clear               # Clear conversation history and start new thread
/threads             # Browse and resume previous threads
/trace               # Open current thread in LangSmith
/changelog           # Open CLI changelog in browser
/docs                # Open documentation in browser
/feedback            # File bug report or feature request
/version             # Show version
/quit                # Exit CLI (alias: /q)
/help                # Show all commands
```

## Non-Interactive Mode

For automation and scripting — runs a single task and exits (see [Workflows & Patterns](references/workflows.md) for CI/CD recipes):

```bash
# Basic task
deepagents -n "Analyze this codebase for security issues"

# With shell access (default: no shell in non-interactive)
deepagents -n "Run tests and report failures" --shell-allow-list recommended
deepagents -n "Search logs for errors" --shell-allow-list ls,cat,grep

# Auto-approve all tool calls
deepagents --auto-approve -n "Generate docs for all modules"

# Specific model
deepagents -M ollama:qwen3:8b -n "Explain this code"
```

**Shell access in non-interactive mode** is disabled by default. Use `--shell-allow-list`:
- `recommended` — safe defaults
- `ls,cat,grep,...` — explicit comma-separated list

### Piping and stdin

The CLI accepts piped input via stdin. When input is piped, the CLI automatically runs non-interactively:

```bash
# Pipe content for analysis
echo "Explain this code" | deepagents
cat error.log | deepagents -n "What's causing this error?"
git diff | deepagents -n "Review these changes"

# Clean output for piping to other commands
deepagents -n "Generate a .gitignore for Python" -q > .gitignore
deepagents -n "List dependencies" -q --no-stream | sort
```

When piped input is combined with `-n` or `-m`, the piped content is prepended to the flag's value. The maximum piped input size is 10 MiB.

## Model Selection

See [Providers & Models](references/providers.md) for all 20+ supported providers, API key setup, and config.toml format. See also the [official providers guide](https://docs.langchain.com/oss/python/deepagents/cli/providers).

### At Launch

```bash
deepagents -M anthropic:claude-sonnet-4-5
deepagents -M openai:gpt-4o
deepagents -M ollama:qwen3:8b
```

### During Session

```bash
/model                          # Interactive picker
/model anthropic:claude-opus-4-6  # Direct switch
```

### Default Model

```bash
deepagents --default-model anthropic:claude-sonnet-4-5  # Set default
deepagents --default-model                               # Show current
deepagents --clear-default-model                         # Clear default
```

### Resolution Order

1. `-M` flag (always wins)
2. `[models].default` in `~/.deepagents/config.toml`
3. `[models].recent` (last `/model` switch, auto-saved)
4. First available API key: `OPENAI_API_KEY` → `ANTHROPIC_API_KEY` → `GOOGLE_API_KEY` → `GOOGLE_CLOUD_PROJECT`

## Skills Management

See [Skills System](references/skills-system.md) for the full SKILL.md format and progressive disclosure. See also the [official skills docs](https://docs.langchain.com/oss/python/deepagents/skills).

```bash
deepagents skills create my-skill             # Create user skill
deepagents skills create my-skill --project   # Create project skill
deepagents skills list                        # List user skills
deepagents skills list --project              # List project skills
deepagents skills info my-skill               # Show skill details
deepagents skills delete my-skill             # Delete user skill
deepagents skills delete my-skill --project   # Delete project skill
```

**User skills:** `~/.deepagents/<agent>/skills/`
**Project skills:** `<project>/.deepagents/skills/` (requires `.git` in project root)

Project skills override user skills with the same name.

## Sandbox Execution

Run agent code in isolated environments (see [Sandboxes](references/sandboxes.md) for setup guides and [official sandbox docs](https://docs.langchain.com/oss/python/deepagents/sandboxes)):

```bash
deepagents --sandbox modal --sandbox-setup ./setup.sh
deepagents --sandbox runloop
deepagents --sandbox daytona
deepagents --sandbox langsmith
deepagents --sandbox-id EXISTING_ID    # Reuse sandbox
```

Sandbox providers: **Modal** (ML/GPU), **Runloop** (disposable devboxes), **Daytona** (fast cold starts), **LangSmith** (cloud deployment).

## Built-in Tools

| Tool | Description | Approval Required |
|------|-------------|:-:|
| `ls` | List files/directories | — |
| `read_file` | Read file contents; supports images (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) | — |
| `write_file` | Create/overwrite files | ✓ |
| `edit_file` | Targeted string replacements | ✓ |
| `glob` | Find files by pattern | — |
| `grep` | Search file contents | — |
| `shell` | Execute shell commands (local) | ✓ |
| `execute` | Execute in sandbox | ✓ |
| `web_search` | Search web (Tavily) | ✓ |
| `fetch_url` | Fetch web pages as markdown | ✓ |
| `task` | Delegate to [subagents](references/sdk-customization.md#subagents) | ✓ |
| `write_todos` | Task planning/tracking | — |

Use `--auto-approve` or `Shift+Tab` in REPL to bypass approval prompts.

## Common Workflows

### Code Analysis (Safe, Read-Only)

```bash
deepagents -n "Analyze src/ for code quality issues"
```

### Code Generation with File Writing

```bash
deepagents --auto-approve -n "Generate unit tests for src/auth.py"
```

### Research with Memory Persistence

```bash
deepagents -a researcher -m "Research best practices for Python async"
# Agent saves findings to memories/ automatically
# Next session:
deepagents -a researcher -m "What did we learn about async?"
```

### Project-Scoped Agent

```bash
cd my-project
# Create .deepagents/AGENTS.md with project conventions
mkdir -p .deepagents
echo "# Project uses FastAPI, PostgreSQL, pytest" > .deepagents/AGENTS.md
deepagents -m "Help me add a new API endpoint"
```

## Configuration

Global config: `~/.deepagents/config.toml` (see [Providers & Models](references/providers.md) for the full config.toml schema)

```toml
[models]
default = "anthropic:claude-sonnet-4-5"

[models.providers.ollama]
base_url = "http://localhost:11434"
models = ["qwen3:8b", "llama3"]

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192
```

## References

For detailed documentation:

- **[CLI Reference](references/cli-reference.md)** — Complete flags, commands, slash commands, keyboard shortcuts
- **[Providers & Models](references/providers.md)** — All 20+ providers, config.toml format, model switching
- **[Skills System](references/skills-system.md)** — Creating skills, progressive disclosure, SKILL.md format
- **[Memory & Persistence](references/memory-and-persistence.md)** — Auto-memory, AGENTS.md, SDK long-term memory
- **[Sandboxes](references/sandboxes.md)** — Modal/Runloop/Daytona setup, security considerations
- **[SDK Customization](references/sdk-customization.md)** — create_deep_agent(), middleware, subagents, backends
- **[Workflows & Patterns](references/workflows.md)** — Automation, CI/CD, subagent patterns, troubleshooting
- **[Streaming](references/streaming.md)** — Streaming modes, subgraph streaming, frontend integration
- **[Agent Client Protocol](references/acp.md)** — ACP server, editor integrations (Zed, VSCode, JetBrains, Neovim)

## Tips

- **`@filename` in REPL** auto-completes and injects file contents into your prompt
- **`!command`** runs shell commands directly without agent interpretation
- **`/remember [context]`** explicitly triggers memory/skill updates — pass optional context to guide the update
- **`-n` mode has no shell by default** — add `--shell-allow-list recommended` for safe commands
- **Local models** (Ollama) work for simple tasks but may struggle with complex tool-calling — use Anthropic/OpenAI for multi-step work
- **Reset an agent** with `deepagents reset --agent NAME` if memories accumulate irrelevant info