Deep Agents CLI

Interactive command-line interface for building with Deep Agents

The Deep Agents CLI is an open source coding assistant that runs in your terminal and retains persistent memory. Your CLI agents maintain context across sessions, learn project conventions, and execute code with approval controls.

The Deep Agents CLI has the following built-in capabilities:

• File operations - read, write, and edit files in your project with tools that enable agents to manage and modify code and documentation.
• Shell command execution - execute shell commands to run tests, build projects, manage dependencies, and interact with version control systems.
• Web search - search the web for up-to-date information and documentation (requires Tavily API key).
• HTTP requests - make HTTP requests to APIs and external services for data fetching and integration tasks.
• Task planning and tracking - break down complex tasks into discrete steps and track progress through the built-in todo system.
• Memory storage and retrieval - store and retrieve information across sessions, enabling agents to remember project conventions and learned patterns.
• Human-in-the-loop - require human approval for sensitive tool operations.

Watch the demo video to see how the Deep Agents CLI works.

Quick start

1. Set your API key

   Export as an environment variable:

   export ANTHROPIC_API_KEY="your-api-key"
   

   Or create a .env file in your project root:

   ANTHROPIC_API_KEY=your-api-key
   
2. Run the CLI

   Install globally

   uv tool install deepagents-cli
   deepagents
   
3. Give the agent a task

   > Create a Python script that prints "Hello, World!"
   

   The agent proposes changes with diffs for your approval before modifying files.

Configure tracing (optional)

Enable LangSmith tracing:

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY="your-api-key"

Configure agent tracing for tool calls and agent decisions:

export DEEPAGENTS_LANGSMITH_PROJECT="my-agent-project"

Configure user code tracing for code executed with shell commands:

export LANGSMITH_PROJECT="my-user-code-project"

Additional installation and configuration options

Install locally if needed:

pip

pip install deepagents-cli

The CLI automatically selects a provider based on which API keys are available. If multiple keys are set, it uses the first match in this order:

Priority	API key	Default model
1st	OPENAI_API_KEY	gpt-5-mini
2nd	ANTHROPIC_API_KEY	claude-sonnet-4-5-20250929
3rd	GOOGLE_API_KEY	gemini-3-pro-preview

To use a different model, pass the --model flag explicitly. For example, to use Claude Opus 4.5:

deepagents --model claude-opus-4-5-20251101

Enable web search (optional):

export TAVILY_API_KEY="your-key"

API keys can be set as environment variables or in a .env file.

Configuration

Command-line options

Option	Description
--agent NAME	Use named agent with separate memory
--auto-approve	Skip tool confirmation prompts (toggle with Ctrl+T)
--resume, -r	Resume most recent session
--sandbox TYPE	Execute in remote sandbox: modal, daytona, or runloop
--sandbox-id ID	Reuse existing sandbox
--sandbox-setup PATH	Run setup script in sandbox
--version	Display version

CLI commands

Command	Description
deepagents list	List all agents
deepagents help	Show help
deepagents reset --agent NAME	Clear agent memory and reset to default
deepagents reset --agent NAME --target SOURCE	Copy memory from another agent
deepagents threads list	List all sessions
deepagents threads delete ID	Delete a session

Interactive mode

Slash commands

Use these commands within the CLI session:

• /tokens - Display token usage
• /clear - Clear conversation history
• /exit or /quit - Exit the CLI
• /help - Show help
• /threads - Show session info
• /version - Show version

Bash commands

Execute shell commands directly by prefixing with !:

!git status
!npm test
!ls -la

Keyboard shortcuts

Shortcut	Action
Enter	Submit
Option+Enter (Mac) or Alt+Enter (Windows)	Newline
Ctrl+E	External editor
Shift+Tab	Toggle auto-approve
@filename	Auto-complete files and inject content
Ctrl+C	Interrupt
Ctrl+D	Exit

Set project conventions with memories

Agents store information in ~/.deepagents/AGENT_NAME/memories/ as markdown files using a memory-first protocol:

1. Research: Searches memory for relevant context before starting tasks
2. Response: Checks memory when uncertain during execution
3. Learning: Automatically saves new information for future sessions

The agent organizes its memories by topic with descriptive filenames:

~/.deepagents/backend-dev/memories/
├── api-conventions.md
├── database-schema.md
└── deployment-process.md

When you teach the agent conventions:

uvx deepagents-cli --agent backend-dev
> Our API uses snake_case and includes created_at/updated_at timestamps

It remembers for future sessions:

> Create a /users endpoint
# Applies conventions without prompting

Use remote sandboxes

Execute code in isolated remote environments for safety and flexibility. Remote sandboxes provide the following benefits:

• Safety: Protect your local machine from potentially harmful code execution
• Clean environments: Use specific dependencies or OS configurations without local setup
• Parallel execution: Run multiple agents simultaneously in isolated environments
• Long-running tasks: Execute time-intensive operations without blocking your machine
• Reproducibility: Ensure consistent execution environments across teams

To use a remote sandbox, follow these steps:

1. Configure your sandbox provider (Runloop, Daytona, or Modal):

   # Runloop
   export RUNLOOP_API_KEY="your-key"
   
   # Daytona
   export DAYTONA_API_KEY="your-key"
   
   # Modal
   modal setup
   

2. Run the CLI with a sandbox:

   uvx deepagents-cli --sandbox runloop --sandbox-setup ./setup.sh
   

   The agent runs locally but executes all code operations in the remote sandbox. Optional setup scripts can configure environment variables, clone repositories, and prepare dependencies.

3. (Optional) Create a setup.sh file to configure your sandbox environment:

   #!/bin/bash
   set -e
   
   # Clone repository using GitHub token
   git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
   cd $HOME/workspace
   
   # Make environment variables persistent
   cat >> ~/.bashrc <<'EOF'
   export GITHUB_TOKEN="${GITHUB_TOKEN}"
   export OPENAI_API_KEY="${OPENAI_API_KEY}"
   cd $HOME/workspace
   EOF
   
   source ~/.bashrc
   

   Store secrets in a local .env file for the setup script to access.

Sandboxes isolate code execution, but agents remain vulnerable to prompt injection with untrusted inputs. Use human-in-the-loop approval, short-lived secrets, and trusted setup scripts only.

Note that sandbox APIs are evolving rapidly, and we expect more providers to support proxies that help mitigate prompt injection and secrets management concerns.

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.