deepagents-cli
Description
🧠🤖 Deep Agents CLI
Quick Install
curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/scripts/install.sh | bash# With model provider extras (OpenAI is included by default)
DEEPAGENTS_EXTRAS="anthropic,groq" curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/scripts/install.sh | bashOr install directly with uv:
# Install with chosen model providers (OpenAI is included by default)
uv tool install 'deepagents-cli[anthropic,groq]'Run the CLI:
deepagents🤔 What is this?
The fastest way to start using Deep Agents. deepagents-cli is a pre-built coding agent in your terminal — similar to Claude Code or Cursor — powered by any LLM that supports tool calling. One install command and you're up and running, no code required.
What the CLI adds on top of the SDK:
- Interactive TUI — rich terminal interface with streaming responses
- Conversation resume — pick up where you left off across sessions
- Web search — ground responses in live information
- Remote sandboxes — run code in isolated environments (Modal, Runloop, Daytona, & more)
- Persistent memory — agent remembers context across conversations
- Custom skills — extend the agent with your own slash commands
- Headless mode — run non-interactively for scripting and CI
- Human-in-the-loop — approve or reject tool calls before execution
📖 Resources
- CLI Documentation
- Changelog
- Source code
- Deep Agents SDK — underlying agent harness
📕 Releases & Versioning
See our Releases and Versioning policies.
💁 Contributing
As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
For detailed information on how to contribute, see the Contributing Guide.
🤝 Acknowledgements
This project was primarily inspired by Claude Code, and initially was largely an attempt to see what made Claude Code general purpose, and make it even more so.
Classes
Class
ApprovalPreview
Data used to render HITL previews.
Class
FileOpMetrics
Line and byte level metrics for a file operation.
Class
FileOperationRecord
Track a single filesystem tool call.
Class
FileOpTracker
Collect file operation metrics during a CLI interaction.
Class
MCPToolInfo
Metadata for a single MCP tool.
Class
MCPServerInfo
Metadata for a connected MCP server and its tools.
Class
MCPSessionManager
Manages persistent MCP sessions for stateful stdio servers.
Class
ModelStats
Token stats for a single model within a session.
Class
SessionStats
Stats accumulated over a single agent turn (or full session).
Class
TextualUIAdapter
Adapter for rendering agent output to Textual widgets.
Class
LocalContextState
State for local context middleware.
Class
LocalContextMiddleware
Inject local context (git state, project structure, etc.) into the system prompt.
Class
HITLIterationLimitError
Raised when the HITL interrupt loop exceeds _MAX_HITL_ITERATIONS rounds.
Class
StreamState
Mutable state accumulated while iterating over the agent stream.
Class
ThreadUrlLookupState
Best-effort background LangSmith thread URL lookup state.
Class
Choice
A single choice option for a multiple choice question.
Class
Question
A question to ask the user.
Class
AskUserRequest
Request payload sent via interrupt when asking the user questions.
Class
AskUserAnswered
Widget result when the user submits answers.
Class
AskUserCancelled
Widget result when the user cancels the prompt.
Class
AskUserMiddleware
Middleware that provides an ask_user tool for interactive questioning.
Class
ParsedPastedPathPayload
Unified parse result for dropped-path payload detection.
Class
MediaTracker
Track pasted images and videos in the current conversation.
Class
SubagentMetadata
Metadata for a custom subagent loaded from filesystem.
Class
UnicodeIssue
A dangerous Unicode character found in text.
Class
UrlSafetyResult
Safety analysis output for a URL string.
Class
CharsetMode
Character set mode for TUI display.
Class
Glyphs
Character glyphs for TUI display.
Class
Settings
Global settings and environment detection for deepagents-cli.
Class
SessionState
Mutable session state shared across the app, adapter, and agent.
Class
ModelResult
Result of creating a chat model, bundling the model with its metadata.
Class
QueuedMessage
Represents a queued user message awaiting processing.
Class
TextualTokenTracker
Token tracker that updates the status bar.
Class
TextualSessionState
Session state for the Textual app.
Class
DeepAgentsApp
Main Textual application for deepagents-cli.
Class
AppResult
Result from running the Textual application.
Class
ThreadInfo
Thread metadata returned by list_threads.
Class
ImageData
Represents a pasted image with its base64 encoding.
Class
VideoData
Represents a pasted video with its base64 encoding.
Class
ModelConfigError
Raised when model configuration or creation fails.
Class
ModelSpec
A model specification in provider:model format.
Class
ModelProfileEntry
Profile data for a model with override tracking.
Class
ProviderConfig
Configuration for a model provider.
Class
ModelConfig
Parsed model configuration from config.toml.
Class
FormattedOutput
Result of formatting tool output for display.
Class
UserMessage
Widget displaying a user message.
Class
QueuedUserMessage
Widget displaying a queued (pending) user message in grey.
Class
AssistantMessage
Widget displaying an assistant message with markdown support.
Class
ToolCallMessage
Widget displaying a tool call with collapsible output.
Class
DiffMessage
Widget displaying a diff with syntax highlighting.
Class
ErrorMessage
Widget displaying an error message.
Class
AppMessage
Widget displaying an app message.
Class
SummarizationMessage
Widget displaying a summarization completion notification.
Class
MCPToolItem
A selectable tool item in the MCP viewer.
Class
MCPViewerScreen
Modal viewer for active MCP servers and their tools.
Class
CompletionResult
Result of handling a key event in the completion system.
Class
CompletionView
Protocol for views that can display completion suggestions.
Class
CompletionController
Protocol for completion controllers.
Class
SlashCommandController
Controller for / slash command completion.
Class
FuzzyFileController
Controller for @ file completion with fuzzy matching from project root.
Class
MultiCompletionManager
Manages multiple completion controllers, delegating to the active one.
Class
EnhancedDiff
Widget for displaying a unified diff with syntax highlighting.
Class
Spinner
Animated spinner using charset-appropriate frames.
Class
LoadingWidget
Animated loading indicator with status text and elapsed time.
Class
ApprovalMenu
Approval menu using standard Textual patterns.
Class
Decided
Message sent when user makes a decision.
Class
ModelLabel
A label that displays a model name, right-aligned with smart truncation.
Class
StatusBar
Status bar showing mode, auto-approve, cwd, git branch, tokens, and model.
Class
ModelOption
A clickable model option in the selector.
Class
Clicked
Message sent when a model option is clicked.
Class
ModelSelectorScreen
Full-screen modal for model selection.
Class
HistoryManager
Manages command history with file persistence.
Class
AskUserMenu
Interactive widget for asking the user questions.
Class
Answered
Message sent when user submits all answers.
Class
Cancelled
Message sent when user cancels the ask_user prompt.
Class
ToolApprovalWidget
Base class for tool approval widgets.
Class
GenericApprovalWidget
Generic approval widget for unknown tools.
Class
WriteFileApprovalWidget
Approval widget for write_file - shows file content with syntax highlighting.
Class
EditFileApprovalWidget
Approval widget for edit_file - shows clean diff with colors.
Class
ThreadOption
A clickable thread option in the selector.
Class
Clicked
Message sent when a thread option is clicked.
Class
DeleteThreadConfirmScreen
Confirmation modal shown before deleting a thread.
Class
ThreadSelectorScreen
Modal dialog for browsing and resuming threads.
Class
ToolRenderer
Base renderer for tool approval widgets.
Class
WriteFileRenderer
Renderer for write_file tool - shows full file content.
Class
EditFileRenderer
Renderer for edit_file tool - shows unified diff.
Class
CompletionOption
A clickable completion option in the autocomplete popup.
Class
Clicked
Message sent when a completion option is clicked.
Class
CompletionPopup
Popup widget that displays completion suggestions as clickable options.
Class
OptionClicked
Message sent when a completion option is clicked.
Class
ChatTextArea
TextArea subclass with custom key handling for chat input.
Class
Submitted
Message sent when text is submitted.
Class
HistoryPrevious
Request previous history entry.
Class
HistoryNext
Request next history entry.
Class
PastedPaths
Message sent when paste payload resolves to file paths.
Class
ChatInput
Chat input widget with prompt, multi-line text, autocomplete, and history.
Class
Submitted
Message sent when input is submitted.
Class
ModeChanged
Message sent when input mode changes.
Class
MessageType
Types of messages in the chat.
Class
ToolStatus
Status of a tool call.
Class
MessageData
In-memory message data for virtualization.
Class
MessageStore
Manages message data and widget window for virtualization.
Class
WelcomeBanner
Welcome banner displayed at startup.
Class
ModalBackend
Modal backend implementation conforming to SandboxBackendProtocol.
Class
ModalProvider
Modal sandbox provider implementation.
Class
LangSmithBackend
LangSmith backend implementation conforming to SandboxBackendProtocol.
Class
LangSmithProvider
LangSmith sandbox provider implementation.
Class
SandboxError
Base error for sandbox provider operations.
Class
SandboxNotFoundError
Raised when the requested sandbox cannot be found.
Class
SandboxProvider
Interface for creating and deleting sandbox backends.
Class
RunloopBackend
Backend that operates on files in a Runloop devbox.
Class
RunloopProvider
Runloop sandbox provider implementation.
Class
DaytonaBackend
Daytona backend implementation conforming to SandboxBackendProtocol.
Class
DaytonaProvider
Daytona sandbox provider implementation.
Class
ExtendedSkillMetadata
Extended skill metadata for CLI display, adds source tracking.
Functions
Function
dispatch_hook
Fire matching hook commands with payload serialized as JSON on stdin.
Function
dispatch_hook_fire_and_forget
Schedule dispatch_hook as a background task with a strong reference.
Function
find_project_root
Find the project root by looking for .git directory.
Function
find_project_agent_md
Find project-specific AGENTS.md file(s).
Function
compute_unified_diff
Compute a unified diff between before and after content.
Function
resolve_physical_path
Convert a virtual/relative path to a physical filesystem path.
Function
format_display_path
Format a path for display.
Function
build_approval_preview
Collect summary info and diff for HITL approvals.
Function
load_mcp_config
Load and validate MCP configuration from JSON file.
Function
discover_mcp_configs
Find MCP config files from standard locations.
Function
classify_discovered_configs
Split discovered config paths into user-level and project-level.
Function
extract_stdio_server_commands
Extract stdio server entries from a parsed MCP config.
Function
merge_mcp_configs
Merge multiple MCP config dicts by server name.
Function
load_mcp_config_lenient
Load an MCP config file, returning None on any error.
Function
get_mcp_tools
Load MCP tools from configuration file with stateful sessions.
Function
resolve_and_load_mcp_tools
Resolve MCP config and load tools.
Function
format_token_count
Format a token count into a human-readable short string.
Function
print_usage_table
Print a model-usage stats table to a Rich console.
Function
execute_task_textual
Execute a task with output directed to Textual UI.
Function
build_detect_script
Concatenate all section functions into the full detection script.
Function
check_cli_dependencies
Check if CLI optional dependencies are installed.
Function
check_optional_tools
Check for recommended external tools and return missing tool names.
Function
format_tool_warning_tui
Format a missing-tool warning for the TUI toast.
Function
format_tool_warning_cli
Format a missing-tool warning for non-interactive Rich console output.
Function
parse_args
Parse command line arguments.
Function
run_textual_cli_async
Run the Textual CLI interface (async version).
Function
apply_stdin_pipe
Read piped stdin and merge it into the parsed CLI arguments.
Function
cli_main
Entry point for console script.
Function
run_non_interactive
Run a single task non-interactively and exit.
Function
parse_file_mentions
Extract @file mentions and return the text with resolved file paths.
Function
parse_pasted_file_paths
Parse a paste payload that may contain dragged-and-dropped file paths.
Function
parse_pasted_path_payload
Parse dropped-path payload variants through one entrypoint.
Function
parse_single_pasted_file_path
Parse and resolve a single pasted path payload.
Function
extract_leading_pasted_file_path
Extract and resolve a leading pasted path token from input text.
Function
normalize_pasted_path
Normalize pasted text that may represent a single filesystem path.
Function
build_help_parent
Build a parent parser whose -h invokes help_fn.
Function
show_help
Show top-level help information for the deepagents CLI.
Function
show_list_help
Show help information for the list subcommand.
Function
show_reset_help
Show help information for the reset subcommand.
Function
show_skills_help
Show help information for the skills subcommand.
Function
show_skills_list_help
Show help information for the skills list subcommand.
Function
show_skills_create_help
Show help information for the skills create subcommand.
Function
show_skills_info_help
Show help information for the skills info subcommand.
Function
show_skills_delete_help
Show help information for the skills delete subcommand.
Function
show_threads_help
Show help information for the threads subcommand.
Function
show_threads_delete_help
Show help information for the threads delete subcommand.
Function
show_threads_list_help
Show help information for the threads list subcommand.
Function
list_subagents
List subagents from user and/or project directories.
Function
detect_dangerous_unicode
Detect deceptive or hidden Unicode code points in text.
Function
strip_dangerous_unicode
Remove known dangerous/invisible Unicode characters from text.
Function
render_with_unicode_markers
Render hidden Unicode characters as explicit markers.
Function
summarize_issues
Summarize Unicode issues for warning messages.
Function
format_warning_detail
Join safety warnings into a display string with overflow indicator.
Function
check_url_safety
Check a URL for suspicious Unicode and domain spoofing patterns.
Function
iter_string_values
Flatten nested dict/list structures into key-path/string pairs.
Function
looks_like_url_key
Return whether a key path suggests URL-like content.
Function
get_glyphs
Get the glyph set for the current charset mode.
Function
reset_glyphs_cache
Reset the glyphs cache (for testing).
Function
newline_shortcut
Return the platform-native label for the newline keyboard shortcut.
Function
get_banner
Get the appropriate banner for the current charset mode.
Function
parse_shell_allow_list
Parse shell allow-list from string.
Function
contains_dangerous_patterns
Check if a command contains dangerous shell patterns.
Function
is_shell_command_allowed
Check if a shell command is in the allow-list.
Function
get_langsmith_project_name
Resolve the LangSmith project name if tracing is configured.
Function
fetch_langsmith_project_url
Fetch the LangSmith project URL via the LangSmith client.
Function
build_langsmith_thread_url
Build a full LangSmith thread URL if tracing is configured.
Function
reset_langsmith_url_cache
Reset the LangSmith URL cache (for testing).
Function
get_default_coding_instructions
Get the default coding agent instructions.
Function
detect_provider
Auto-detect provider from model name.
Function
create_model
Create a chat model.
Function
validate_model_capabilities
Validate that the model has required capabilities for deepagents.
Function
run_textual_app
Run the Textual application.
Function
format_timestamp
Format ISO timestamp for display (e.g., 'Dec 30, 6:10pm').
Function
format_relative_timestamp
Format ISO timestamp as relative time (e.g., '5m ago', '2h ago').
Function
format_path
Format a filesystem path for display.
Function
get_db_path
Get path to global database.
Function
generate_thread_id
Generate a new 8-char hex thread ID.
Function
list_threads
List threads from checkpoints table.
Function
populate_thread_message_counts
Populate message_count for an existing thread list.
Function
populate_thread_checkpoint_details
Populate checkpoint-derived fields for an existing thread list.
Function
prewarm_thread_message_counts
Prewarm thread selector cache for faster /threads open.
Function
get_cached_threads
Get cached recent threads, if available.
Function
apply_cached_thread_message_counts
Apply cached message counts onto thread rows when freshness matches.
Function
apply_cached_thread_initial_prompts
Apply cached initial prompts onto thread rows when freshness matches.
Function
populate_thread_initial_prompts
Populate initial_prompt for thread rows in the background.
Function
get_most_recent
Get most recent thread_id, optionally filtered by agent.
Function
get_thread_agent
Get agent_name for a thread.
Function
thread_exists
Check if a thread exists in checkpoints.
Function
find_similar_threads
Find threads whose IDs start with the given prefix.
Function
delete_thread
Delete thread checkpoints.
Function
get_checkpointer
Get AsyncSqliteSaver for the global database.
Function
get_thread_limit
Read the thread listing limit from DA_CLI_RECENT_THREADS.
Function
list_threads_command
CLI handler for deepagents threads list.
Function
delete_thread_command
CLI handler for: deepagents threads delete.
Function
compute_config_fingerprint
Compute a SHA-256 fingerprint over sorted, concatenated config contents.
Function
is_project_mcp_trusted
Check whether a project's MCP config is trusted with the given fingerprint.
Function
trust_project_mcp
Persist trust for a project's MCP config.
Function
revoke_project_mcp_trust
Remove trust for a project's MCP config.
Function
get_clipboard_image
Attempt to read an image from the system clipboard.
Function
get_image_from_path
Read and encode an image file from disk.
Function
get_video_from_path
Read and encode a video file from disk.
Function
get_media_from_path
Try to load a file as an image first, then as a video.
Function
encode_to_base64
Encode raw bytes to a base64 string.
Function
create_multimodal_content
Create multimodal message content with text, images, and videos.
Function
list_agents
List all available agents.
Function
reset_agent
Reset an agent to default or copy from another agent.
Function
get_system_prompt
Get the base system prompt for the agent.
Function
create_cli_agent
Create a CLI-configured agent with flexible options.
Function
clear_caches
Reset module-level caches so the next call recomputes from scratch.
Function
get_available_models
Get available models dynamically from installed LangChain provider packages.
Function
get_model_profiles
Load upstream profiles merged with config.toml overrides.
Function
has_provider_credentials
Check if credentials are available for a provider.
Function
get_credential_env_var
Return the env var name that holds credentials for a provider.
Function
save_default_model
Update the default model in config file.
Function
clear_default_model
Remove the default model from the config file.
Function
is_warning_suppressed
Check if a warning key is suppressed in the config file.
Function
suppress_warning
Add a warning key to the suppression list in the config file.
Function
load_thread_columns
Load thread column visibility from config file.
Function
save_thread_columns
Save thread column visibility to config file.
Function
load_thread_relative_time
Load the relative-time display preference for thread timestamps.
Function
save_thread_relative_time
Save the relative-time display preference for thread timestamps.
Function
load_thread_sort_order
Load the sort order preference for the thread selector.
Function
save_thread_sort_order
Save the sort order preference for the thread selector.
Function
save_recent_model
Update the recently used model in config file.
Function
http_request
Make HTTP requests to APIs and web services.
Function
web_search
Search the web using Tavily for current information and documentation.
Function
fetch_url
Fetch content from a URL and convert HTML to markdown format.