deepagents_code

Configure runtime logging and register target for per-thread files.

Attach the in-memory buffer handler to target (idempotent).

Lowers target's level to at most INFO so the console shows a useful tail even when DEEPAGENTS_CODE_DEBUG is off; never raises the level. In __init__.py this runs before configure_debug_logging, which then sets the final level (honoring DEEPAGENTS_CODE_DEBUG and DEEPAGENTS_CODE_LOG_LEVEL) over this INFO floor — so any startup warnings configure_debug_logging emits are captured by the already-installed buffer. On a fresh NOTSET logger the NOTSET branch forces INFO without consulting DEEPAGENTS_CODE_LOG_LEVEL; the > INFO and no env branch only matters on reconfiguration (e.g. an importlib.reload), where it preserves an explicit DEEPAGENTS_CODE_LOG_LEVEL rather than clobbering it with INFO.

Lowering the level does not spill log output onto the terminal: because this handler is present in the propagation chain, Logger.callHandlers finds a handler (found > 0) and Python's lastResort stderr handler is never consulted. The exception is an embedding process that attaches its own INFO-or-lower handler to the root logger, which would then see the propagated records.

Note: this runs as an import-time side effect (see __init__.py), so every import deepagents_code attaches the handler and may lower the package logger's level to INFO for the lifetime of the process.

Raised when the launch-time profile location cannot be resolved.

Covers an unsupported DEEPAGENTS_HOME value and a launch home that cannot be determined or is itself unusable. It is a ValueError subclass so existing handlers that expect a bad-value error keep working.

Shared provider auth status formatting.

Server-side graph entry point for langgraph dev.

This module is referenced by the generated langgraph.json and exposes a graph factory that the LangGraph server can load and serve.

The graph is created by 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.

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.

Help screens and argparse utilities for the app.

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

Persistent store of MCP server names the user has disabled.

Disabled servers are skipped at config merge time so their tools never reach the agent and no connection is attempted. State lives under [mcp].disabled_servers in ~/.deepagents/config.toml, alongside the user's other MCP configuration.

The store keys on server name alone. Two configs that both declare a github server will both be disabled by a single entry — intentional, since the agent cannot distinguish overlapping names at runtime anyway (later configs in the merge order win).

Terminal capability detection.

Detect optional terminal features without reading from stdin.

The app only uses kitty-keyboard-protocol support to choose a user-facing newline shortcut label. To keep startup safe on remote or high-latency PTYs, detection is conservative and relies on side-effect-free terminal identity signals plus an explicit environment-variable override.

Agent middleware covering what MCP tools need around every call.

The tools themselves come out of langchain.mcp unmodified. Everything this app wants on top — an argument quirk, and translating a dead-token failure into something a model and a user can act on — sits here instead, so the adapter stays the plain conversion it is and this behavior applies to any MCP tool the agent is given.

Auto-install pinned upstream binaries for optional tools.

Today this only manages ripgrep. The SDK shells out to rg via PATH, so installing inside the dcode tool environment and prepending that directory to os.environ["PATH"] is sufficient — no SDK change required. Keeping helper binaries installation-scoped lets multiple profiles reuse one verified binary.

FALLBACK_BIN_DIR covers the case where that shared directory is not writable (a system or root-owned sys.prefix). Run dcode doctor to see which of the two locations is actually in use.

The pinned RIPGREP_VERSION, archive hashes in RIPGREP_ASSETS, and extracted binary hashes in RIPGREP_BINARY_SHA256 are the source of truth for what gets downloaded and executed. Refresh all three together when bumping the version.

Shared size limits and status vocabulary for model-visible goal state.

Estimate and persist cumulative model cost for each thread.

The graph owns the durable total. CostTrackingMiddleware writes ordinary graph deltas, while prepare_operation_cost gives server-owned operations a rollback-safe delta to commit with their state update. Each cost update therefore rides a graph checkpoint and works for local, headless, and remote execution without a client-side state update -- the middleware also runs in local in-process agents, where there is no server and the delta rides the local checkpoint. The client is a reader: it renders the streamed total and never maintains its own lifetime figure.

Side questions use an isolated recorder and persist their subtotal in the sessions database (see btw_cost). They can finish after the graph stops, so their spend cannot depend on a later checkpoint. The client combines the independently reported subtotals only for presentation.

Coverage is not limited to the agent's own model node. Offload/summarization and the Auto mode classifier invoke a model directly, outside after_model, and subagents run their own graph. _SessionCostRecorder — a callback handler installed process-wide for every model request (see _install_recorder) — collects one record per completed request, keyed by thread, and CostTrackingMiddleware drains and prices those records on the main agent's checkpoint path. New side invokes are covered with no extra wiring.

The recorder only collects; the middleware alone prices and writes. The agent's own response is still priced from state, but only when the recorder did not already charge that message ID, so a request is never counted twice. That fallback keeps main-agent cost correct even for a model that never fires callbacks.

Nested agents first checkpoint their own spend on the same private channel. That makes a completed model call durable before a later tool approval can interrupt the subgraph. When the subagent finishes, its middleware transfers the accumulated delta through an owner-scoped state entry. The subagent tool checkpoints that entry on the parent graph even when a sibling interrupts, while the private total itself remains isolated between graphs.

Every caller uses estimate_cost, the only function that imports or calls genai-prices. The import is lazy so the package and its bundled pricing data stay off the CLI startup path. On that first successful import a daemon-thread updater starts refreshing the catalog from upstream hourly (see _start_price_updater); DEEPAGENTS_CODE_PRICES_AUTO_UPDATE=0 or [update].prices_auto_update = false in config.toml opts out, and DEEPAGENTS_CODE_OFFLINE suppresses it along with every other network fetch. When the active genai-prices catalog -- the bundled data, or the auto-updated snapshot once one is installed -- has no rates for a model, a local override catalog is consulted as a fallback-on-miss (see _override_price): the user's own ~/.deepagents/prices.json first, then a maintainer-curated file shipped as package data. PRICING.md documents the former for users and bundled_prices.README.md the latter for maintainers. Unsupported models and malformed usage return None; pricing must never interrupt a model turn.

Main entry point and loop.

External event ingress for the Textual app.

Exposes a small EventSource protocol plus a Unix-domain-socket implementation that lets local processes push commands, prompts, and signals into a running session over a newline-delimited JSON wire protocol.

Subagent loader for app.

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

External editor support for composing prompts.

Utilities for project root detection and project-specific configuration.

Custom tools for the agent.

Shared unified-diff helpers.

Every diff passing through this module is "\n"-joined from lines that came from splitlines() or split("\n"), so no element can contain a line boundary. That is what makes split_diff_lines the exact inverse and splitlines() wrong here — see its docstring for what breaks. Check any helper added to this module, and any new producer of a diff it reads, against that invariant.

Helpers for tracking file operations and computing diffs for display.

Provider policy and pricing helpers for cold prompt-cache warnings.

Dcode-specific ACP approval-mode adapter.

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

Model configuration management.

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

Registry of pending actionable notifications.

Stores plain data for notices the user can act on from a dedicated modal screen. The registry is deliberately UI-agnostic: UI routing (toast click, keybinds) lives in the app layer.

One-time migration of legacy state files into ~/.deepagents/.state/.

Earlier versions wrote internal state directly under ~/.deepagents/, mixing it with user-facing agent directories (so e.g. mcp-tokens/ showed up in deepagents agents list). State now lives in a dedicated .state/ subdirectory; this module moves any legacy files into place on startup.

The migration is best-effort and idempotent: it skips entries whose destination already exists, logs and continues on per-entry failures, and never blocks startup on I/O errors.

Durable, server-authoritative thread workspace bindings.

Reasoning effort support for /effort.

Supported levels and defaults come from LangChain model profiles. Provider integrations translate the standard reasoning_effort constructor parameter into their native request shapes.

Validation and environment-variable expansion for MCP server config.

Resolves ${VAR} and ${VAR:-default} references in the supported configuration fields (command, url, args, env, headers) and validates their types. A ${VAR:-default} reference falls back to default when VAR is unset or empty (POSIX :- semantics).

Schema and middleware for per-checkpoint state restored when resuming.

ResumeState declares several checkpointed, schema-private channels. They fall into two groups with different write paths:

Written from inside the graph on successful model turns:

• _context_tokens — total context tokens from the latest AIMessage.usage_metadata, written by ResumeStateMiddleware.after_model. Powers /tokens and the status bar.
• _model_spec / _model_params — the model and invocation params effectively in use for the turn, written by ConfigurableModelMiddleware after a successful model call. Lets dcode -r restore the model the resumed thread was actually using instead of falling back to the user's global default.
• _last_model_request_at / _last_cache_model_spec — UTC request-start time and requested model identity captured by ConfigurableModelMiddleware and committed only after that call succeeds. Lets the TUI detect when the provider's reusable prompt prefix may be cold.

Written through the main graph or by the TUI client via aupdate_state (see DeepAgentsApp._persist_goal_rubric_state) — these are user/agent-owned. Their write sites are called out below:

• _goal_objective / _goal_status / _goal_rubric / _goal_status_note — the accepted goal and its lifecycle status. _goal_objective/_goal_rubric are client-only, but _goal_status/_goal_status_note are also written from inside the graph by the agent's update_goal tool.
• _pending_goal_completion_note — optional agent-provided completion evidence awaiting the post-turn rubric result.
• _sticky_rubric — the TUI-owned persistent rubric. This is separate from the public rubric graph input so one-shot rubric turns can be checkpointed without being restored as sticky state.
• _rubric_model_spec — the thread-scoped rubric-grader model selection, written by the TUI client. It is a tri-state: absent means the thread has recorded no selection, so the grader keeps its construction-time default; INHERIT_RUBRIC_MODEL means the grader follows the active main model; any other value is a dedicated model spec.
• _pending_goal_objective / _pending_goal_rubric / _pending_goal_kind / _pending_goal_request_id — a proposed goal or amendment and its originating request, written by GoalCriteriaMiddleware inside the main graph, then cleared by the TUI when the user accepts or rejects it.

All of these are facts the CLI reads back from state_values on thread resume so it can rehydrate the session without replaying or re-tokenizing history.

The model-turn channels are persisted from inside the graph (rather than via a separate client-side aupdate_state call) so the write rides the same checkpoint as the model response and avoids creating a standalone UpdateState run in LangSmith. Because they are versioned channel state, resuming a specific checkpoint yields the values as of that checkpoint — not a thread-level aggregate. Accepted goal/rubric state is client-written because the user sets it outside any model turn; pending criteria proposals and agent-driven status updates are graph-written. Both paths work identically against local and remote (HTTP) graphs.

Safe, structured diagnostics for workspace binding and runtime rejections.

When the server refuses to bind or run a thread's workspace, the user sees only a one-line refusal. This module defines the small, explicitly allowlisted comparison snapshot persisted beside each durable binding (so a later refusal can name what changed) and the structured diagnostics carried by WorkspaceConflictError, the workspace HTTP route, and the TUI.

The snapshot allowlist is the security boundary: only policy fields whose values are booleans, integers, tool-name/command allowlists, or short enum-like identifiers may be recorded and reported. Model parameters, model specs, profile overrides, system prompts, environment values, credentials, and paths (which can embed user names or project structure) are never persisted or logged — and never hashed as a reporting workaround.

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

Update lifecycle for deepagents-code.

Handles version checking against PyPI (with caching), install-method detection, auto-upgrade execution, config-driven opt-in/out, notification throttling, 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.

Agent management and creation.

CLI-specific rubric middleware customizations.

Lightweight text-formatting helpers.

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

The dcode doctor command: report install health and diagnostics.

Inspired by claude doctor, this prints a grouped, tree-style summary of the running install, update status, and configuration locations so the output is safe to paste into a bug report. It stays offline: the update section reads only the local cache and never contacts PyPI.

Help rendering for dcode doctor -h is served by ui.show_doctor_help, which does not import this module, so the help path stays light.

Persist side-question spend separately from the running graph's checkpoints.

The sessions database owns this subtotal. Readers add it to the graph's total; it is never fed back into the graph's cost recorder or checkpoint channels. Failed charges retain only usage and pricing metadata, never the conversation. Once priced, a charge is retried without recalculating its price. Only successfully persisted charges survive a server restart.

Storage paths for offloaded conversation history.

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.

Inspect optional-dependency install status for the running distribution.

Reads Requires-Dist metadata to report which packages declared under [project.optional-dependencies] are installed, and renders that status in either plain text (for stdout) or markdown (for rich UI contexts).

Enumerate the tools available to the agent.

Backs two entry points: the dcode tools list CLI command (_run_tools_list) and the interactive /tools slash command (app._handle_tools_command).

The tool set is read from the real tool objects the agent binds rather than a hand-maintained catalog, so names and descriptions never drift from what the model actually sees. Built-in tools are collected by compiling the agent with a throwaway offline chat model (no credentials, no network) and reading the bound tool node; MCP tools are discovered via the same path the app and server use.

The collection functions here lazily import the heavy agent stack (agent compilation, MCP discovery) inside their bodies. Only the fake-model base is imported at module top, so importing this module is cheap relative to the agent stack — and this module is itself imported lazily by both entry points (_run_tools_list and _handle_tools_command), never on the startup hot path.

First-run onboarding state for the interactive TUI.

Formatting utilities for tool call display in the app.

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.

Protect machine-managed memory blocks from agent edits.

The onboarding flow writes the user's preferred name into the user AGENTS.md inside a marker-delimited block (see onboarding.ONBOARDING_NAME_MEMORY_START / ONBOARDING_NAME_MEMORY_END). MemoryMiddleware strips HTML comments before injecting memory, so the model never sees those markers and has no way to know the region is off-limits. Since the same prompt tells the model to edit_file that file to persist learnings, nothing stops it from rewriting the managed block.

This middleware intercepts write_file/edit_file calls targeting the guarded file(s), and delete calls that would remove them. When a write or edit would change or remove the managed block, the model's other edits are kept (though surrounding whitespace may be normalized, and a fully removed block is re-appended rather than restored in place) while the managed block is restored, and an error is returned so the model learns the region is machine-managed. A delete call that would remove an existing managed block is rejected before the tool runs; a delete of a guarded file that exists but cannot be read is also rejected, failing closed rather than removing a file we cannot inspect. When the block was altered but the restore could not be completed, an error is still returned so the failure is never silent.

Classifier-backed approval policy for local TUI and ACP runtimes.

Server-side helpers for drafting acceptance criteria from goal objectives.

iTerm2 cursor guide workaround for Textual alternate-screen rendering.

Backend recovery at the proxy boundary, before errors reach the wire.

LangChain brand colors and semantic constants for the app.

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, $mode-incognito, $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 get_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.

UI-agnostic helpers for resolving an MCP login target.

The MCP login flow historically inlined config discovery, trust gating, shape validation, and print()-based error reporting. The TUI cannot consume those print statements, so this module extracts the same logic into pure functions that return structured results (ConfigResolution, ServerSelection) plus a typed ConfigResolutionError. Callers decide how to render those results.

No print() calls live in this module. No imports happen at module top level beyond dataclasses/typing/pathlib so the CLI fast path stays cheap; the actual config loaders are imported inside the functions that need them.

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

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.

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

Unified slash-command registry.

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

Clipboard utilities.

User-level credential storage for model providers.

Persists API keys (and, in the future, OAuth tokens) under ~/.deepagents/.state/auth.json (file mode 0600, parent 0700) so users can enter credentials directly in the TUI rather than exporting environment variables before launch.

Security notes:

• The stored value (ApiKeyCredential.key) must never be logged, formatted via %r/!r, or interpolated into exception messages — every helper here reports only structural facts ("set credential for provider X").
• The file is written via O_EXCL | 0o600 to a temp path, then atomically replaced. A second chmod 0600 runs on the final path so filesystems that ignore the create-mode argument still end up with private perms. Permission failures are reported back to the caller in WriteOutcome.warnings so the UI can surface them to the user — logger.warning alone is invisible inside a Textual TUI session.
• On Windows, POSIX mode bits don't apply; the chmod calls are best-effort and skipped silently.

Tool-free side answers from a snapshot of the main conversation.

Canonical internal model-context messages for goal state and continuation.

Goal context is represented as a HumanMessage so it participates in the provider's normal turn ordering. Its lc_source marks it as framework-owned model context rather than conversational user input; transcript, title, and derived-conversation projections must therefore hide it.

Best-effort writer for terminal escape/control sequences.

Centralizes the "fire and forget" pattern the app uses for cosmetic terminal control (OSC 9;4 taskbar progress today; eventually OSC 52 clipboard and the iTerm2 cursor guide). Writes prefer /dev/tty so output reaches the terminal even when stdout/stderr are redirected, fall back to sys.__stderr__, and never raise — cosmetic control output must not crash the app.

Set DEEPAGENTS_CODE_NO_TERMINAL_ESCAPE=1 to disable all output (useful for unsupported terminals or noisy logs).

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.

Estimated context audit for the /context-doctor command.

Approval-mode state shared by the Textual client and agent server.

Large paste collapsing for the chat input.

When the user pastes text exceeding a size or line threshold, the full text is stored off-screen and a compact [Pasted text #N +M lines] placeholder is inserted into the input box instead. At submission time the placeholder is expanded back to the original content so the agent receives the full text.

This mirrors the behavior of Claude Code's paste-collapsing system.

Integrations for external systems used by the Deep Agents Code.

Public contract for dcode Python extensions.

Provider-specific MCP OAuth dispatch.

resolve_provider(url) returns the registered policy whose matches predicate fires for url, with GenericProvider as the fallback.

Plugin support for dcode.

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

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

Client-side transport and headless execution for Deep Agents Code.

Hook contracts and compatibility dispatch.

This package contains two hook systems: Hooks v2 (current) and legacy hooks (deprecated, removal September 1, 2026).

To write a new hook integration, use the v2 config format — see deepagents_code.hooks.loading for file locations and precedence, and deepagents_code.hooks.models.config + deepagents_code.hooks.models.wire for the schema and stdin payload shapes.

deepagents_code.hooks.legacy exists only for backward compatibility; new integrations should not target it.

Textual user interface package for deepagents-code.

Skills module for Deep Agents Code.

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.

Managed and user configuration: paths, providers, and merge.

Writes live in deepagents_code.configuration.writer and are imported from there directly, so no writer symbol is re-exported here.