deepagents_cli

Ask user middleware for interactive question-answering during agent execution.

Clipboard utilities for deepagents-cli.

Main entry point and CLI loop for deepagents.

Model configuration management.

Handles loading and saving model configuration from TOML files, providing a structured way to define available models and providers.

Agent management and creation for the CLI.

Business logic for the /offload command.

Extracts the core offload workflow from the UI layer so it can be tested independently of the Textual app.

Server lifecycle orchestration for the CLI.

Provides start_server_and_get_agent which handles the full flow of:

1. Building a ServerConfig from CLI arguments
2. Writing config to env vars via ServerConfig.to_env()
3. Scaffolding a workspace (langgraph.json, checkpointer, pyproject)
4. Starting the langgraph dev server
5. Returning a RemoteAgent client

Also provides server_session, an async context manager that wraps server startup and guaranteed cleanup so callers don't need to duplicate try/finally teardown.

Subagent loader for CLI.

Loads custom subagent definitions from the filesystem. Subagents are defined as markdown files with YAML frontmatter in the agents/ directory.

Thread management using LangGraph's built-in checkpoint persistence.

Help screens and argparse utilities for the CLI.

This module is imported at CLI startup to wire -h actions into the argparse tree. It must stay lightweight — no SDK or langchain imports.

Unified slash-command registry.

Every slash command is declared once as a SlashCommand entry in COMMANDS. Bypass-tier frozensets and autocomplete tuples are derived automatically — no other file should hard-code command metadata.

Helpers for tracking file operations and computing diffs for CLI display.

Custom tools for the CLI agent.

Formatting utilities for tool call display in the CLI.

This module handles rendering tool calls and tool messages for the TUI.

Imported at module level by textual_adapter (itself deferred from the startup path). Heavy SDK dependencies (e.g., backends) are deferred to function bodies.

MCP (Model Context Protocol) tools loader for deepagents CLI.

This module provides async functions to load and manage MCP servers using langchain-mcp-adapters, supporting Claude Desktop style JSON configs. It also supports automatic discovery of .mcp.json files from user-level and project-level locations.

External editor support for composing prompts.

Utilities for handling image and video media from clipboard and files.

Server-side graph entry point for langgraph dev.

This module is referenced by the generated langgraph.json and exposes the CLI agent graph as a module-level variable that the LangGraph server can load and serve.

The graph is created at module import time via make_graph(), which reads configuration from ServerConfig.from_env() — the same dataclass the CLI uses to write the configuration via ServerConfig.to_env(). This shared schema ensures the two sides stay in sync.

Update lifecycle for deepagents-cli.

Handles version checking against PyPI (with caching), install-method detection, auto-upgrade execution, config-driven opt-in/out, and "what's new" tracking.

Most public entry points absorb errors and return sentinel values. set_auto_update raises on write failures so callers can surface actionable feedback.

Trust store for project-level MCP server configurations.

Manages persistent approval of project-level MCP configs that contain stdio servers (which execute local commands). Trust is fingerprint-based: if the config content changes, the user must re-approve.

Trust entries are stored in ~/.deepagents/config.toml under [mcp_trust.projects].

LangChain brand colors and semantic constants for the CLI.

Single source of truth for color values used in Python code (Rich markup, Content.styled, Content.from_markup). CSS-side styling should reference Textual CSS variables: built-in variables ($primary, $background, $text-muted, $error-muted, etc.) are set via register_theme() in DeepAgentsApp.__init__, while the few app-specific variables ($mode-bash, $mode-command, $skill, $skill-hover, $tool, $tool-hover) are backed by these constants via App.get_theme_variable_defaults().

Code that needs custom CSS variable values should call get_css_variable_defaults(dark=...). For the full semantic color palette, look up the ThemeColors instance via ThemeEntry.REGISTRY.

Users can define custom themes in ~/.deepagents/config.toml under [themes.<name>] sections. Each new theme section must include label (str); dark (bool) defaults to False if omitted (set to True for dark themes). Color fields are optional and fall back to the built-in dark/light palette based on the dark flag. Sections whose name matches a built-in theme override its colors without replacing it. See _load_user_themes() for details.

Machine-readable JSON output helpers for CLI subcommands.

This module deliberately stays stdlib-only so it can be imported from CLI startup paths without pulling in unnecessary dependency trees.

CLI middleware for runtime model selection via LangGraph runtime context.

Allows switching the model per invocation by passing a CLIContext via context= on agent.astream() / agent.invoke() without recompiling the graph.

LangGraph server lifecycle management for the CLI.

Handles starting/stopping a langgraph dev server process and generating the required langgraph.json configuration file.

Unicode security helpers for deceptive text and URL checks.

This module is intentionally lightweight so it can be imported in display and approval paths without affecting startup performance.

Non-interactive execution mode for deepagents CLI.

Provides run_non_interactive which runs a single user task against the agent graph, streams results to stdout, and exits with an appropriate code.

The agent runs inside a langgraph dev server subprocess, connected via the RemoteAgent client (see server_manager.server_session).

Shell commands are gated by an optional allow-list (--shell-allow-list):

• Not set → shell disabled, all other tool calls auto-approved.
• recommended or explicit list → shell enabled, commands validated against the list; non-shell tools approved unconditionally.
• all → shell enabled, any command allowed, all tools auto-approved.

An optional quiet mode (--quiet / -q) redirects all console output to stderr, leaving stdout exclusively for the agent's response text.

Textual UI adapter for agent execution.

Textual UI application for deepagents-cli.

Remote agent client — thin wrapper around LangGraph's RemoteGraph.

Delegates streaming, state management, and SSE handling to langgraph.pregel.remote.RemoteGraph. The only added logic is converting raw message dicts from the server into LangChain message objects that the CLI's Textual adapter expects.

Lightweight hook dispatch for external tool integration.

Loads hook configuration from ~/.deepagents/hooks.json and fires matching commands with JSON payloads on stdin. Subprocess work is offloaded to a background thread so the caller's event loop is never stalled. Failures are logged but never bubble up to the caller.

Config format (~/.deepagents/hooks.json):

{"hooks": [{"command": ["bash", "adapter.sh"], "events": ["session.start"]}]}

If events is omitted or empty the hook receives all events.

Input handling utilities including image/video tracking and file mention parsing.

Middleware for injecting local context into system prompt.

Detects git state, project structure, package managers, runtimes, and directory layout by running a bash script via the backend. Because the script executes inside the backend (local shell or remote sandbox), the same detection logic works regardless of where the agent runs.

Configuration, constants, and model creation for the CLI.

Utilities for project root detection and project-specific configuration.

Lightweight text-formatting helpers.

Keep this module free of heavy dependencies so it can be imported anywhere in the CLI without pulling in large frameworks.

Integrations for external systems used by the deepagents CLI.

Skills module for deepagents CLI.

Public API:

• execute_skills_command: Execute skills subcommands (list/create/info/delete)
• setup_skills_parser: Setup argparse configuration for skills commands

All other components are internal implementation details.

Textual widgets for deepagents-cli.

Import directly from submodules, e.g.:

from deepagents_cli.widgets.chat_input import ChatInput
from deepagents_cli.widgets.messages import AssistantMessage

Built-in skills that ship with the Deep Agents CLI.

These skills are always available at the lowest precedence level. User and project skills with the same name will override them.