deepagents-code

Description

🧠🤖 Deep Agents Code

Deep Agents Code

Quick Install

curl -LsSf https://langch.in/dcode | bash

# With model provider extras
# OpenAI, Anthropic, and Gemini are included by default
curl -LsSf https://langch.in/dcode | DEEPAGENTS_CODE_EXTRAS="nvidia,ollama" bash

Run:

dcode

🤔 What is this?

The fastest way to start using Deep Agents. deepagents-code 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 deepagents-code 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 (LangSmith, AgentCore, Daytona, Modal, Runloop, & 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

🔒 Security model

By default, dcode trusts the directory you run it in. Human-in-the-loop approval gates model-requested tool calls, but project artifacts are read before any approval prompt.

Do not run dcode in a directory you do not trust without a sandbox backend. For untrusted repositories, use a remote sandbox so execution is isolated from your machine. Running dcode in a directory lets that directory's files shape execution. See THREAT_MODEL.md for details.

📖 Resources

Documentation
Changelog
Source code
Deep Agents SDK — underlying agent harness
LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
Code of Conduct — community guidelines and standards

📕 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 local setup, see the Development Guide. For contribution policy, 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

ReliableRubricState

Rubric state carrying dcode's private runtime model selections.

These three channels are declared a second time here, because this middleware's state_schema must list every channel it reads. Each a

Class

RubricGraderState

Nested-grader state used to scope verification-tool budgets.

Class

ReliableRubricMiddleware

Run a context-aware nested grader with CLI verification middleware.

The nested grader receives Deep Agents Code's verification middleware and runtime context without requiring those application-speci

Class

BypassTier

Classification that controls whether a command can skip the message queue.

Class

SlashCommand

A single slash-command definition.

Class

CommandEntry

A single autocomplete entry for the slash-command controller.

Class

ImageData

Represents a pasted image with its base64 encoding.

Class

VideoData

Represents a pasted video with its base64 encoding.

Class

ApiKeyCredential

A persisted API key credential.

The type field is the discriminator that lets OAuthCredential (added later) coexist in the same file without migration.

Class

OAuthCredential

A persisted OAuth subscription credential.

Stub kept here so the StoredCredential discriminated union narrows correctly today and the OAuth implementation lands as a pure addition. No code path pro

Class

WriteOutcome

Result of a credential write that may have warnings to surface.

Class

DeleteOutcome

Result of a credential delete that may have warnings to surface.

A delete rewrites the whole store, so it can hit the same chmod failures as a write. warnings carries them symmetrically with `Write

Class

ServerConfig

Full configuration payload passed from the app to the server subprocess.

Serialized to/from DEEPAGENTS_CODE_SERVER_* environment variables so that the server graph (which runs in a separate Python

Class

SubagentMetadata

Metadata for a custom subagent loaded from filesystem.

Class

OutputTruncation

Why a provider stopped a reply early.

Class

ModelOutputTruncatedError

The model stopped before it gave any reply.

Subclasses ValueError so that the LangGraph server keeps the message when it serializes the error for the client. Other exception types are redacted to "

Class

EmptyTruncatedReplyMiddleware

Fail the main run when the provider cut off a reply before any output.

Without this, a reply with no text, no tool calls, and a truncation stop reason ends the run as a success. The empty message is

Class

SubagentTruncatedReplyMiddleware

Keep partial subagent answers and fail empty ones for the parent to handle.

Class

DeterministicIntegrationChatModel

Deterministic chat model for integration tests.

This subclasses _ToolBindingFakeModel (itself a GenericFakeChatModel) so the implementation stays aligned with the core fake-chat-model test surfac

Class

ToolCallingIntegrationChatModel

Deterministic tool-calling model for auto-approve integration tests.

Generation is driven entirely by prompt markers (the module-level DCA_* constants), so output is restart-safe and independent of

Class

GoalCriteriaIntegrationChatModel

Exercise nested criteria generation with a repository read.

Class

GoalRubricChannels

Goal/rubric state channels shared by every schema that touches them.

Declared once here so each schema that carries these channels — ResumeState and goal_tools.GoalToolState — inherits the same

Class

ResumeState

Extends agent state with per-checkpoint facts restored on resume.

Inherits the shared goal/rubric channels from GoalRubricChannels and adds the channels unique to resume: the after-model token/spec

Class

ResumeStateMiddleware

Persists per-checkpoint resume facts after each model call.

See the module docstring for why this rides the model node's checkpoint instead of a separate aupdate_state (avoids a standalone `UpdateS

Class

MCPBackendMiddleware

Recover failed connections and preserve actionable login errors.

Class

InMemoryLogRecord

Structured log record retained by the in-memory debug buffer.

Class

InMemoryLogBuffer

Logging handler retaining the most recent structured records in memory.

Retention is partitioned by level: each recognized level name (see LOG_LEVELS) keeps its own bounded deque of capacity re

Class

BtwOperation

Capture effective main-call context and answer tool-free side questions.

Register after middleware that modifies the model, prompt, or settings, including extensions. ConfigurableModelMiddleware re

Class

PastedContent

Stored content for a collapsed paste.

The paste's numeric identifier is the key under which this record is stored in the input's paste map, so it is not duplicated on the record.

Class

GoalStateProjection

Canonical goal/rubric fields used for notices and fingerprints.

Class

NoticeTextSections

The three user-controlled text sections a goal-state notice can embed.

Named rather than a bare tuple[str | None, str | None, str | None]: all five call sites unpack positionally and immediately re

Class

GoalStateNoticeInfo

Metadata extracted from a canonical goal-state notice.

Class

WorkspaceSnapshot

Versioned, allowlisted policy snapshot persisted beside a binding.

Class

FieldChange

One drifted policy field, reported within the snapshot allowlist.

Class

WorkspaceDiagnostics

Structured, secret-free detail attached to a workspace refusal.

Class

MCPProviderToolSearchMiddleware

Defer only currently exposed MCP tools on verified native endpoints.

Class

WorkspacePayload

JSON-safe workspace descriptor carried in LangGraph runtime context.

Class

WorkspaceBinding

Server-authoritative workspace and resource policy for one thread.

Class

WorkspaceConflictError

A workspace claim or runtime conflicts with server resource policy.

Class

DeepAgentsHomeError

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

Class

ConfigErrorKind

Discriminator for ConfigResolutionError reasons.

Only NO_CONFIG_FOUND maps to exit code 2 in the mcp login CLI handlers (run_mcp_login, run_mcp_login_list); all other kinds map to exit code

Class

ConfigResolutionError

Structured error returned when a login target cannot be resolved.

Class

ConfigResolution

Successful resolution of a merged MCP config for login.

Class

ServerSelection

Resolved server config plus enough context for error messages.

Class

AgentServerACP

ACP server that supplies trusted classifier context in Auto mode.

Class

ServerRuntime

The one-per-process result with named slots to prevent transposition.

Class

TerminalStderrGuard

Suppress native stderr writes while the TUI owns the terminal.

Class

CatalogProfile

Displayable model capabilities with override provenance.

Class

CatalogProvider

Provider presentation and readiness, without credential values.

Class

ModelCatalog

Validated catalog from the environment that constructs models.

Class

UnicodeIssue

A dangerous Unicode character found in text.

Class

UrlSafetyResult

Safety analysis output for a URL string.

A result may have safe=True with non-empty warnings when informational warnings (e.g. punycode decoding) are present without suspicious patterns.

Class

ActionId

Stable identifiers for notification actions dispatched by the app.

Class

NotificationAction

One button/action row in the notification modal.

Class

MissingDepPayload

Typed payload for a missing-dependency notification.

Class

UpdateAvailablePayload

Typed payload for an update-available notification.

Class

PendingNotification

A single notice waiting for user action.

Immutable value object: the registry owns the key-to-toast-identity binding (see NotificationRegistry) so external callers cannot corrupt click-routing indi

Class

NotificationRegistry

In-memory store of pending notifications.

Instance-scoped (one per app) so test apps don't pollute each other. Owns the bidirectional key-to-toast-identity binding so callers cannot accidentally desy

Class

ModelMetadata

Resolved model properties needed by the interactive client.

Class

DiffStats

Line counts for a change, named so the pair cannot be swapped silently.

Keyword-only and frozen so that claim holds at construction as well as in transit: a positional pair is exactly the transpositi

Class

CLIContextSchema

Declared context_schema for the agent graph.

Registered via context_schema= when the graph is built, so LangGraph coerces each run's context= payload into this dataclass — in-process, `runtime.

Class

CLIContext

Client-facing builder for the per-run graph context payload.

Callers populate this and pass it via context= to astream/ainvoke. ConfigurableModelMiddleware and the interrupt_on when predi

Class

ProjectContext

Explicit user/project path context for project-sensitive behavior.

Class

AskUserMiddleware

Middleware that provides an ask_user tool for interactive questioning.

This middleware adds an ask_user tool that allows agents to ask the user questions during execution. Questions can be free-for

Class

ColdCacheSkip

A known reason to skip a cache prompt, distinct from missing pricing.

Class

CacheActivity

A cache-using request's start time and effective cache identity.

Class

PromptCachePolicy

Prompt-cache behavior needed to decide and price a warning.

Keyword-only because window_seconds and minimum_tokens are adjacent bare ints: positionally, transposing them builds a plausible-lookin

Class

RewarmEstimate

Estimated input cost for a cold prefix and its warm-cache delta.

Both figures are USD, non-negative, and finite; incremental_cost_usd is the part of cold_cost_usd that a cache hit would have avoi

Class

ColdCacheWarning

Validated data needed to render one advisory warning.

Constructed only after every gate has passed -- a policy resolved, the prefix cleared the provider's cache minimum, and the priced delta reached

Class

ShellAllowListMiddleware

Validate shell commands against an allow-list without HITL interrupts.

When the agent invokes the execute shell tool, this middleware checks the command against the configured allow-list **before e

Class

AsyncApprovalHITLMiddleware

Stock HITL routing with an async live-mode read after model completion.

The transient routing marker is added only to a shallow state copy passed directly into stock HITL routing. It is neither check

Class

CachingRuleProcessor

Apply secret rules per string and remember the result in a bounded LRU.

The output for a string is the same whether it comes from the cache or from the rules, so the cache cannot let a secret through

Class

ExternalEditorError

Raised when an external editor cannot be opened or read.

Class

ProfilePaths

Paths whose contents belong to one user profile and trust root.

Class

InstallationPaths

Paths owned by the installed tool rather than a selected profile.

Class

ProjectPaths

Project-controlled paths derived from an explicit repository root.

Class

DeepAgentsPathSnapshot

Frozen launch-time profile and installation paths.

Class

PathState

Whether a probed path exists, is absent, or could not be read.

A StrEnum so the value serializes directly to JSON without a custom encoder.

Class

GitTraceMiddleware

Observe backend work and backfill only the initiating user turn.

Class

GoalStateSizeError

Goal/rubric text exceeds a model-visible context budget.

Class

TurnTrace

Keep sibling invocation roots alive until the thread starts another turn.

Class

LocalContextState

State for local context middleware.

Class

LocalContextMiddleware

Inject local context (git state, project structure, etc.) into the system prompt.

Runs a bash detection script via backend.execute() on first interaction and stores that snapshot for stable system-

Class

GitSnapshot

Repository identity and opaque non-content evidence of checkout work.

Class

ContextDoctorRow

One component in the context audit.

Class

ContextDoctorReport

Structured context audit ready for presentation.

Class

LocalMarketplaceSource

Local directory or JSON file used as a marketplace source.

Class

RepositoryMarketplaceSource

GitHub or Git repository used as a marketplace source.

ref selects an optional branch or tag. Commit SHA checkout is not part of the shallow-clone flow.

Class

UrlMarketplaceSource

Marketplace manifest downloaded from an HTTP URL.

Class

PluginManifest

Parsed plugin manifest.

Class

ComponentInventory

Inventory of supported plugin components.

unsupported lists plugin component directories that deepagents-code does not load (e.g. agents/, commands/).

Class

PluginInstance

A discovered plugin ready to feed dcode adapters.

Class

LocalPluginSource

A plugin stored relative to its marketplace.

Class

GithubPluginSource

A plugin sourced from a GitHub repository.

Class

GitSubdirectoryPluginSource

A plugin sourced from a subdirectory in a Git repository.

Class

UrlPluginSource

A plugin sourced from a Git repository URL.

Class

MarketplacePluginEntry

A catalog entry from a marketplace manifest.

Class

PluginMarketplace

A parsed marketplace manifest.

Class

MarketplaceRecord

Persisted marketplace source record.

Class

InstalledPluginEntry

Install record for a plugin.

version is the value declared by the plugin manifest, if any.

Class

BrokenPluginInstall

An enabled, registered plugin whose installed files are missing.

Class

PluginDiscoveryResult

Result from plugin discovery.

broken lists enabled plugins whose installed files are missing. They are reported separately from warnings so callers can present them once with repair guidance inst

Class

PluginUpdate

A marketplace plugin version that differs from the installed one.

Class

PluginUpdateResult

Outcome of checking installed plugins against their marketplaces.

Class

MarketplaceError

Raised when a marketplace cannot be loaded.

Class

SandboxProviderConfig

Configuration for a single config-declared sandbox provider.

Warning

Setting class_path executes arbitrary Python code imported from the user's config file. This has the same trust mod

Class

SandboxConfig

Parsed [sandboxes] configuration from config.toml.

Instances are immutable once constructed; providers is wrapped in a MappingProxyType to prevent accidental mutation.

Class

SandboxInstallHint

How to install the package that provides a sandbox backend.

Built-in providers ship as deepagents-code extras (kind="extra"); third-party providers install as arbitrary packages (kind="package"

Class

SandboxProviderMetadata

Static description of a sandbox provider used by the registry.

Lets the CLI and registry describe built-in and config providers without instantiating them (which may require credentials or optional d

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

CodexAuthStatus

Snapshot of the ChatGPT OAuth login state.

Class

CodexLoginCancelledError

Raised when the user cancels a sign-in flow mid-callback wait.

Class

CodexAuthExpiredError

Raised when a stored ChatGPT token cannot be refreshed.

Distinct from a missing token (FileNotFoundError): a token exists on disk but its refresh token was revoked or expired, so an automatic refre

Class

CodexLoginInteraction

UI hooks for the browser loopback sign-in flow.

Implementations decide how to surface the authorize URL and whether to auto-open a browser. The Textual screen subclasses this; CLI / headless callers

Class

SandboxRegistry

Merged view of built-in, entry-point, and config sandbox providers.

Class

HookSessionIdentity

Live client identity projected into every hook invocation.

Class

HookOutcome

Result of a lifecycle hook that may halt the caller.

Class

PromptOutcome

Result of UserPromptSubmit, including its prompt rewrites.

Class

HooksManager

Owns the Hooks v2 runtime, presenter, hook service, and transcripts.

The presenter is the manager's, not the runtime's: one instance is created once and handed to every runtime the manager loads, so

Class

HookEnvelopeAdapter

Adapt hook invocations and handler output across the wire boundary.

Class

ClientHookStopError

Raised when a client-owned hook stops lifecycle processing.

Class

ClientHookContext

Client state required to create a domain hook invocation.

Class

ClientHookService

Execute client-owned events and apply their common side effects.

User-facing output goes through the runtime's presenter, which the owning HooksManager also holds. The service never wraps or replac

Class

PermissionReviewDecision

Client approval decision compatible with HITL resume payloads.

Class

PermissionHookOutcome

Normalized result shared by TUI and headless permission handling.

Class

PermissionPlan

How one batch of gated tool calls was resolved by hooks.

Indices refer to positions in the originating action_requests list, so a caller can line outcomes back up with its own UI rows.

Class

PreparedHookInvocation

Client-only materialization needed to build one hook wire envelope.

Class

HooksRuntime

Client-owned session runtime around an immutable Hooks snapshot.

Owns configuration snapshot identity, transcript materialization, and the HookEngine. Server-owned lifecycle events reach this runti

Class

HookHandler

One ordered command handler in a configuration snapshot.

Class

HookMatch

Matched handlers for one invocation.

Class

HooksSnapshot

Immutable, declaration-ordered Hooks v2 runtime configuration.

Class

HookEngine

Execute Hooks v2 invocations against one immutable snapshot.

Class

HooksSource

Origin of the matcher groups contributed by one hooks document.

Class

FileHooksSource

A project or user hooks file, which defines no variables.

Class

PluginHooksSource

Origin and environment for groups one enabled plugin contributed.

Class

LoadedHooksConfig

Validated configuration plus load diagnostics and source paths.

Class

HookFulfillmentLedger

Deduplicate hook fulfillment for one client session.

Class

HookInvocationRequest

Request sent for a server-owned hook invocation.

Class

HookInvocationResponse

Response returned for a server-owned hook invocation.

Class

CommandHandlerSpec

Configuration for a synchronous command hook.

Currently only type: "command" is supported. Additional handler types remain a discriminated-union extension point and are rejected until implemented.

Class

MatcherGroup

A matcher and its ordered hook handlers.

Class

HooksConfig

Top-level configuration grouped by hook event.

Class

ResumeRequest

An explicit -r <id> resume request from the command line.

Class

ResumeTarget

A thread that exists and passes the resume-age policy.

Class

ResumeError

A user-facing reason the requested thread cannot be resumed.

Class

SessionCost

Presentation total derived from the latest independent subtotals.

Class

SessionCostTracker

Retain each source independently so delayed updates cannot erase spend.

Class

ResolvedOption

An option paired with its resolved effective value, for display.

Bundles the four values that always travel together through the render helpers as one named record, so they can't be reordered or misa

Class

PrespawnedServer

A start_server_and_get_agent call that spawns before the app loads.

The subprocess boots while the caller imports and paints the app. The start then pauses until adopt releases it, so the health

Class

GitHubProvider

GitHub-hosted MCP: RFC 8628 Device Authorization Grant.

Class

LoginResult

Outcome of a provider's pre-handshake run_login step.

Class

OAuthProvider

Base class for provider-specific OAuth dispatch.

Subclasses override matches plus whichever of client_metadata and run_login they customize. The default implementations cover the spec-compliant

Class

GenericProvider

Fallback provider for spec-compliant MCP servers with no quirks.

Class

SlackProvider

Slack-hosted MCP: loopback authorization using the selected app.

Class

SkillInvocationEnvelope

Structured prompt and checkpoint metadata for a skill invocation.

Class

ResolvedManagedPath

Where managed policy is read from, and whether that location is certain.

fallback holds why the path is a guess, or None when the path is authoritative. A failed registry query leaves the lookup

Class

InterpreterConfig

Configuration consumed by CodeInterpreterMiddleware.

Class

ConfigSources

Managed and user TOML snapshots from one resolution generation.

Class

ManagedConfigError

Raised when an enforced managed source cannot be read safely.

Class

ManagedPolicyError

Raised when managed policy declares a value that cannot be enforced.

The file parses, so provider health is OK; the policy it states is what cannot be applied. A subclass of ManagedConfigError so

Class

ManagedHealth

Provider health and policy enforceability from one managed snapshot.

Class

WriteResult

Outcome of one user config transaction.

Class

ExtensionRuntimeMiddleware

Expose tools registered after the agent graph was built.

Class

TrustPolicy

Default decision for project-authored extension code.

Class

ExtensionSettings

Effective extension configuration for one process.

Class

ExtensionMode

Runtime mode exposed to extensions.

Class

ExtensionAPI

Factory-scoped registrar and read-only session context.

Each extension receives a dedicated instance, which attributes every registration to the extension's source without exposing mutable dcode appl

Class

ThreadAgentSwitchPromptScreen

Ask before changing agents to resume a thread.

Class

MCPLoginCancelledError

Raised by MCPLoginScreen.action_cancel when the user cancels the flow.

Class

MCPLoginScreen

Modal that renders the OAuth login flow and collects user input.

Implements the OAuthInteraction Protocol structurally so a mcp_auth.login(..., ui=screen) call drives the same modal. Each interac

Class

DetailActionActivated

Posted when an _ActionOption is clicked with the mouse.

Class

NotificationDetailScreen

Modal displaying a single notification's title, body, and actions.

Activation returns the chosen ActionId via dismiss(); Esc returns None so the caller can keep the underlying notification cent

Class

LaunchGoalCriteriaPreferenceScreen

One-time choice for how Auto mode handles generated goal criteria.

Class

LaunchNameScreen

Onboarding screen that asks for the user's name.

Dismissal values:

Non-empty stripped/title-cased name when the user submits one.
"" when the user submits an empty input (continue, but skip na

Class

LaunchDependenciesScreen

Onboarding screen that summarizes installed optional integrations.

Class

ContextUsageScreen

Modal visualization of the current model context window.

Class

CwdSwitchPromptScreen

Modal asking whether to switch cwd when resuming or switching to a thread.

Class

HookTrustScreen

Ask how project hooks in a newly entered workspace should be trusted.

Class

ToolRenderer

Strategy for building a tool's HITL approval widget.

Each renderer maps a tool name to a (widget_class, data) pair that controls what the user sees in the approval box. Tools not registered in `_RE

Class

WriteFileRenderer

Renderer for write_file tool - shows full file content.

Class

TaskRenderer

Renderer for task tool — interrupt description provides full context.

Class

DeleteFileRenderer

Renderer for delete tool - shows removed file content when available.

Class

EditFileRenderer

Renderer for edit_file tool - shows unified diff.

Class

StartupTip

One startup tip displayed above the chat input.

Class

Region

The closed set of LangSmith region selections in the /auth prompt.

Class

ResolvedEndpoint

Outcome of resolving the region selector to an endpoint to persist.

endpoint is the canonical URL to store (empty for the US SaaS default); error is a user-facing message when a Custom URL is mis

Class

AuthResult

Outcome of an AuthPromptScreen interaction.

The three outcomes need to stay distinguishable because callers in the recovery path retry the original failing operation only on SAVED — retrying afte

Class

AuthConfirmScreen

Confirm before launching an authentication flow for a model.

A provider-agnostic gate shown when a selected model needs credentials that aren't detected, and starting the auth flow is disruptive enou

Class

DeleteCredentialConfirmScreen

Confirmation overlay shown before clearing a stored credential.

Patterned on DeleteThreadConfirmScreen so the destructive prompt feels consistent across the app. Always dismisses with True on con

Class

AuthPromptScreen

Modal that captures and persists an API key for one provider.

Dismissal values are members of AuthResult so callers in the recovery path can distinguish "user just saved a key — retry the failed op

Class

AuthManagerScreen

Modal that lists configured providers and lets the user manage keys.

Reachable via the /auth slash command. Always dismisses with None; state changes are persisted by AuthPromptScreen and refle

Class

CredentialSaved

Posted when a key prompt successfully persists credentials.

Carries the /auth config key that was saved so the app can react to credentials that gate spawn-time behavior — e.g. a Tavily key that en

Class

CredentialDeleted

Posted when a key prompt deletes stored credentials.

Carries the /auth config key that was deleted so the app can clear any in-memory state derived from the now-removed credential.

Class

InstallPackageConfirmScreen

Confirmation overlay for installing an arbitrary --package.

Dismisses with True when the user confirms and False when the user cancels. Esc is treated as cancel so the user is never forced into

Class

InstallProviderConfirmScreen

Confirmation overlay for installing a model provider's extra.

Shown from the model selector when the user picks a model whose provider integration package is not installed. Dismisses with True to i

Class

UpdateProgressScreen

Modal that shows self-update progress and a bounded log tail.

Class

AgentSelectorScreen

Modal dialog for switching between available agents.

Displays agent profiles from ~/.deepagents/ (directories that contain an AGENTS.md marker) in an OptionList. Returns the selected agent name

Class

GoalReviewAccepted

Widget result when the generated criteria are accepted unchanged.

Class

GoalReviewEdited

Widget result when the user submits revised criteria.

Class

GoalReviewRejected

Widget result when the user rejects criteria with feedback.

Class

GoalReviewCancelled

Widget result when the user cancels the proposal.

Class

GoalReviewTextArea

Text input that keeps goal-review edit keystrokes inside the editor.

Class

Submitted

Posted when the user presses Enter to submit goal-review text.

Class

CancelEdit

Posted when Escape should leave goal criteria edit mode.

Class

GoalReviewMenu

Inline review widget for generated goal acceptance criteria.

Class

Decided

Message sent when the user accepts, edits, or cancels.

Class

PasteBurstTextArea

TextArea that detects paste-like keystroke bursts.

Subclasses drive the state machine from their own _on_key by calling the helper methods here, and override the policy hooks (`in_slash_command

Class

CollapsingPasteTextArea

Paste-aware text area that collapses large pastes into placeholders.

The full pasted text is stored off-screen in _pasted_contents and a compact [Pasted text #N] placeholder is shown in its place

Class

MessageType

Types of messages in the chat.

Class

ToolStatus

Status of a tool call.

Class

MessageData

In-memory message data for virtualization.

This dataclass holds all information needed to recreate a message widget. It is designed to be lightweight so that thousands of messages can be stored witho

Class

MessageStore

Manages message data and widget window for virtualization.

This class stores all messages as data and manages a sliding window of widgets that are actually mounted in the DOM.

Class

NotificationActionResult

Dismissal payload identifying which action the user picked.

The screen returns this via dismiss() when the user drills into a notification and selects an action; it returns None when the user can

Class

NotificationRowClicked

Posted when a notification row is clicked with the mouse.

Class

NotificationSuppressRequested

Posted when the user picks SUPPRESS from a notification's detail modal.

The center does not dismiss on SUPPRESS because the remaining notifications should still be reachable in place. The app handles

Class

NotificationSettingsRequested

Posted when the user toggles the settings disclosure row.

The app responds by refreshing the open center's settings state from config; the center also handles the message itself so toggles stay respo

Class

NotificationActionRequested

Posted for an action that opens a follow-up modal in place.

Some actions (those in IN_PLACE_ACTIONS, currently ENTER_API_KEY) push another modal, such as the API-key prompt, on top of the still-o

Class

NotificationCenterScreen

Shared hub for pending notifications and warning preferences.

Each PendingNotification is a single row followed by a settings disclosure row. Up/Down (or j/k) moves the cursor; Enter or click drill

Class

MCPReconnectPromptScreen

Modal asking whether to restart the server after an MCP login.

Dismisses with "reconnect" when the user accepts the restart and "later" when the user defers. Esc is treated as "later" so the user

Class

MCPDisableReconnectPromptScreen

Modal asking whether to reconnect after /mcp disable/enable toggles.

Shown when the user closes the /mcp viewer with pending F2 disable-state changes but without pressing Ctrl+R, so the toggl

Class

MCPReconnectForceConfirmScreen

Confirmation overlay for /mcp reconnect --force with no pending login.

Guards a fat-fingered force-restart when nothing is actually queued.

Class

PromptFilterInput

Prompt filter with standard modified-Backspace word deletion.

Class

PromptSearchInput

Query field for the inline prompt search panel.

Plain Input apart from the class name, which lets ChatInput filter Input.Changed / Input.Submitted messages down to this field, plus bindings f

Class

AbandonSearch

Posted on Escape or empty-query Backspace, to close the search.

Class

PromptSearchOption

One clickable prompt row in the inline search panel.

Class

Clicked

Message sent when a prompt row is clicked.

Class

PromptSearchPanel

Inline prompt history search rendered above the input row.

Display-only: ChatInput owns the query, filtered snapshot, and selection, drives key handling, and re-opens the modal tier. The panel mirr

Class

RowsChanged

Message sent when the panel's rendered row count changes.

Class

OptionSelected

Message sent when a prompt row is clicked in the panel.

Class

MCPToolItem

A selectable tool item in the MCP viewer.

Class

MCPServerErrorScreen

Read-only modal for a failed MCP server's error details.

Class

MCPServerHeaderItem

A selectable server-header row in the MCP viewer.

Cursor-selectable so users can navigate to every server — even those in unauthenticated or error states which have no tool rows by the `MCPServer

Class

MCPViewerScreen

Modal viewer for active MCP servers and their tools.

Displays servers grouped by name with transport type and tool count. Navigate with arrow keys, Enter to expand/collapse tool descriptions, start i

Class

ThemeSelectorScreen

Modal dialog for theme selection with live preview.

Displays available themes in an OptionList. Navigating the option list applies a live preview by swapping the app theme. Returns the selected the

Class

ApprovalMenu

Approval menu using standard Textual patterns.

Key design decisions (following mistral-vibe reference):

Container base class with compose()
BINDINGS for key handling (not on_key)
can_focus_chil

Class

Decided

Message sent when user makes a decision.

Class

SkillTrustScreen

Approval overlay for a skill resolving outside trusted directories.

Dismisses with True when the user allows the resolved target and False when the user declines. Esc is treated as deny so the us

Class

AskUserTextArea

Free-form answer input for ask-user questions.

Adds two behaviors over the shared base:

When the cursor is on the first or last line of a choice question's Other free-text input, Up/Down are han

Class

Submitted

Posted when the user presses Enter to submit an ask-user answer.

Class

AskUserMenu

Interactive widget for asking the user questions.

Supports text input, multiple choice (pick exactly one), and multi-select (toggle one or more) questions. Choice questions always include an "Other"

Class

Answered

Message sent when user submits all answers.

Class

Cancelled

Message sent when user cancels the ask_user prompt.

Class

ChangelogClicked

Posted when the changelog row is clicked with the mouse.

Class

UpdateAvailableScreen

Modal dedicated to the update-available notification.

Renders the entry's title and body, a "View changelog" row, and one row per configured action. Dismisses with the selected ActionId, or None

Class

Spinner

Animated spinner using charset-appropriate frames.

Class

LoadingWidget

Animated loading indicator with status text and elapsed time.

Displays: Thinking... (3s, esc to interrupt)

Class

GoalStatusPanel

Keep the current goal and lifecycle state visible above the input.

Class

AutoModeNoticeScreen

In-TUI first-run notice describing what Auto mode does.

Dismisses with True on Enter (confirm switch to Auto) and False on Esc (cancel, stay in current mode). Programmatic dismiss may yield `None

Class

EffortSelectorScreen

Modal dialog for selecting a reasoning effort level.

Class

YoloModeNoticeResult

Outcome of the YOLO first-enable notice.

ACKNOWLEDGE enables YOLO (and records the acknowledgement); MANUAL switches to Manual instead; CANCEL keeps the previous mode. A programmatic dismiss ma

Class

YoloModeNoticeScreen

In-TUI acknowledgement shown before unrestricted YOLO becomes active.

Dismisses with YoloModeNoticeResult.ACKNOWLEDGE on Enter (acknowledge and enable), YoloModeNoticeResult.MANUAL on m (switch

Class

JsEvalStdout

Captured stdout printed during a js_eval evaluation.

Class

JsEvalResult

A successful js_eval evaluation result.

Class

JsEvalError

An error raised during a js_eval evaluation.

Class

CodexAuthScreen

Run the ChatGPT OAuth Authorization Code Flow with PKCE inline.

Dismissal value:

True: a token was saved (caller should refresh provider lists / retry the operation that needed the credentia

Class

CodexSignedInAction

Outcome of the CodexSignedInScreen quick-action overlay.

Encoded as an enum (mirroring AuthResult) rather than bare strings so a typo in either the producing action_* method or the consuming di

Class

CodexSignedInScreen

Quick-action overlay shown when openai_codex is already signed in.

Dismissal values:

CodexSignedInAction.SIGN_OUT: delete the stored token.
CodexSignedInAction.REAUTH: open the OAuth flow

Class

RestartPromptScreen

Modal asking whether to restart the server for a spawn-time change.

Serves both the post-install offer and the post-/auth web-search offer; the caller supplies the title verb and body copy.

Class

CompletionOption

A clickable completion option in the autocomplete popup.

Class

Clicked

Message sent when a completion option is clicked.

Class

InputActionButton

Small clickable button shown at the right edge of the chat input row.

Provides discoverable mouse alternatives to keyboard shortcuts for clearing ([ X ]) and copying ([ COPY ]) the current draft.

Class

Clicked

Message sent when an input action button is clicked.

Class

CompletionPopup

Popup widget that displays completion suggestions as clickable options.

Class

RowsChanged

Message sent when the popup's visible row count changes.

Deduplicated by the sender, so receiving this always means the rendered row count actually moved.

Class

OptionClicked

Message sent when a completion option is clicked.

Class

ChatTextArea

TextArea subclass with custom key handling for chat input.

Modifier-Enter / Ctrl+J newline bindings and the VSCode backslash+enter fallback are inherited from PasteBurstTextArea.

Class

Submitted

Message sent when text is submitted.

Class

HistoryPrevious

Request previous history entry.

Class

HistoryNext

Request next history entry.

Class

Typing

Posted when the user presses a printable key or backspace.

Relayed by ChatInput as ChatInput.Typing for the app to track typing activity.

Class

ChatInputBox

Bordered box that owns the chat composer size.

Sizing is either automatic (content-driven, the default) or manual, and _requested_height is the discriminator: None means automatic.

A manual size

Class

ChatInputResizeHandle

Drag target docked over the chat input's top border.

Only the background is transparent: the handle sits on the layer above the box's border and would blank the line it covers, so render repaints t

Class

DragStarted

Message sent when a resize drag begins.

Class

Dragged

Message sent with the current drag delta.

Class

DragEnded

Message sent when a resize drag stops, however it stopped.

Class

HoverChanged

Message sent when resize hover feedback changes.

Class

ToggleExpanded

Message sent when expanded sizing should be toggled.

Class

ChatInput

Chat input widget with prompt, multi-line text, autocomplete, and history.

Features:

Multi-line input with TextArea
Enter to submit, modifier key for newlines (see config.newline_shortcut)
Up

Class

Submitted

Message sent when input is submitted.

Class

ModeChanged

Message sent when input mode changes.

Class

Typing

Posted when the user presses a printable key or backspace in the input.

The app uses this to delay approval widgets while the user is actively typing, preventing accidental key presses (e.g. y, n

Class

SelectionAction

Floating "Ask about this" button for the current selection.

It snapshots the selected text because clicking it clears the screen selection before the Click arrives.

Class

Ask

Request insertion of the captured selection into the chat input.

Class

UpdateBeforeDependenciesConfirmScreen

Confirmation overlay before /update --deps upgrades dcode itself.

Dismisses with True when the user chooses the app update first and False when they prefer to refresh dependencies for the curre

Class

RefreshDependenciesConfirmScreen

Confirmation overlay for a dependency refresh.

Dismisses with True when the user confirms and False when the user cancels. Esc is treated as cancel so the user is never forced into a refresh they

Class

Theme

Theme facts that change block geometry, colors, or fence highlighting.

Block backgrounds and borders with alpha are inline styles rather than component classes: a partial component style pre-blends i

Class

Layout

Lay out parsed blocks at a width, following Textual's block CSS.

Class

Node

A parsed markdown block.

Class

FinalMarkdown

A finished markdown reply drawn as one widget.

Looks like Textual's Markdown (validated against Textual 8.2.8) but holds no child widgets. Long fence lines fold instead of scrolling.

Class

Row

One rendered line of the reply.

parts holds (content, selectable) pairs. Selectable parts carry the selection offset meta, so they take the text pointer, mouse selection, and copy; the others (

Class