Agent skill

deepagents-cli

Deep Agents CLI reference and usage guide. Use when the user wants to: (1) Launch or configure the deepagents terminal coding assistant, (2) Set up interactive or non-interactive (automation/CI) agent sessions, (3) Manage agent memory, skills, or AGENTS.md context files, (4) Configure LLM providers, models, or sandbox execution environments, (5) Build scripted workflows or subagent patterns with deepagents.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/deepagents-cli-gitmaxd-deepagents-cli-droid

SKILL.md

Deep Agents CLI

Terminal coding agent with persistent memory, skills, sandboxed execution, and 20+ LLM providers. Built on LangGraph. See the official overview and CLI guide.

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:

~/.deepagents/<agent_name>/
├── 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 and Skills System 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 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 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 for all 20+ supported providers, API key setup, and config.toml format. See also the official providers guide.

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 for the full SKILL.md format and progressive disclosure. See also the official skills docs.

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 for setup guides and official sandbox docs):

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 ✓
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 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 — Complete flags, commands, slash commands, keyboard shortcuts
  • Providers & Models — All 20+ providers, config.toml format, model switching
  • Skills System — Creating skills, progressive disclosure, SKILL.md format
  • Memory & Persistence — Auto-memory, AGENTS.md, SDK long-term memory
  • Sandboxes — Modal/Runloop/Daytona setup, security considerations
  • SDK Customization — create_deep_agent(), middleware, subagents, backends
  • Workflows & Patterns — Automation, CI/CD, subagent patterns, troubleshooting
  • Streaming — Streaming modes, subgraph streaming, frontend integration
  • Agent Client Protocol — 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results