The log file defaults to '/tmp/deepagents_debug.log' but can be overridden with DEEPAGENTS_CODE_DEBUG_FILE. The handler appends so that multiple modules share the same log file across a session.

Does nothing when DEEPAGENTS_CODE_DEBUG is not truthy (see is_env_truthy).

function

read_git_branch_from_filesystem

Read the current git branch from repository metadata.

function

read_git_branch_via_subprocess

Fall back to git rev-parse for unusual repository layouts.

function

format_token_count

Format a token count into a human-readable short string.

function

is_ascii_mode

Check whether the terminal is in ASCII charset mode.

Convenience wrapper so widgets can branch on charset without importing both _detect_charset_mode and CharsetMode.

function

restore_iterm_cursor_guide

Restore iTerm2 cursor guide when launch-time profile state required it.

function

open_url_async

Open url in a browser and toast on failure.

Runs webbrowser.open in a thread, catches the platform errors that can arise when no browser backend is available, and posts a warning toast containing the URL so the user can copy it manually instead of the failure vanishing into a background worker log.

function

save_theme_preference

Persist theme preference to ~/.deepagents/config.toml.

function

save_terminal_theme_mapping

Persist a [ui.terminal_themes][term_program] = name entry.

The write is atomic (temp file + Path.replace) to avoid corrupting config.toml on crash or SIGINT. Mirrors save_theme_preference.

function

run_textual_app

Run the Textual application.

When server_kwargs is provided (and agent is None), the app starts immediately with a "Connecting..." banner and launches the server in the background. Server cleanup is handled automatically after the app exits.

Classes

class

CLIContext

Runtime context passed via context= to the LangGraph graph.

Carries per-invocation overrides that ConfigurableModelMiddleware reads from request.runtime.context.

class

SessionStats

Stats accumulated over a single agent turn (or full session).

class

ActionId

Stable identifiers for notification actions dispatched by the app.

class

MissingDepPayload

Typed payload for a missing-dependency notification.

class

NotificationAction

One button/action row in the notification modal.

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 desynchronize the click-routing indices.

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 indices by mutating notifications after construction.

class

UpdateAvailablePayload

Typed payload for an update-available notification.

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/Down arrows for command history at input boundaries (start/end of text)
Autocomplete for @ (files) and / (commands)

class

LoadingWidget

Animated loading indicator with status text and elapsed time.

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

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 without meaningful memory overhead.

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

MessageType

Types of messages in the chat.

class

ToolStatus

Status of a tool call.

class

AppMessage

Widget displaying an app message.

class

AssistantMessage

Widget displaying an assistant message with markdown support.

Uses MarkdownStream for smoother streaming instead of re-rendering the full content on each update. Once a stream finishes, the message is re-rendered from the complete source via Markdown.update() to work around Textualize/textual#6518: MarkdownFence._update_from_block refreshes the visible Label but leaves _highlighted_code pinned to the first chunk, so any later recompose (click, focus change, theme update) re-yields the stale value and wrapped fenced-code bodies vanish. A full re-parse rebuilds every fence with correct internal state.

class

ErrorMessage

Widget displaying an error message.

class

QueuedUserMessage

Widget displaying a queued (pending) user message in grey.

This is an ephemeral widget that gets removed when the message is dequeued.

class

SkillMessage

Widget displaying a skill invocation with collapsible body.

Shows skill name, source badge, description, and user args as a compact header. The full SKILL.md body (frontmatter stripped) is hidden behind a preview/expand toggle (click or Ctrl+O). The expanded view renders markdown via Rich's Markdown inside a single Static widget.

Visibility is driven by a CSS class (-expanded) toggled via a Textual reactive var. Click handlers are scoped to the header and hint widgets (_SkillToggle) so clicks on the rendered markdown body do not trigger expansion toggles (preserving text selection, for instance).

class

ToolCallMessage

Widget displaying a tool call with collapsible output.

Tool outputs are shown as a 3-line preview by default. Press Ctrl+O to expand/collapse the full output. Shows an animated "Running..." indicator while the tool is executing.

class

UserMessage

Widget displaying a user message.

class

StatusBar

Status bar showing mode, auto-approve, cwd, git branch, tokens, and model.

class

WelcomeBanner

Welcome banner displayed at startup.

class

Question

A question to ask the user.

class

EventSource

Source of external events for the Textual app.

Implementations must be safe to stop() even when start() failed partway through; the app always invokes stop() from a finally block.

class

ExternalEvent

A transport-independent event delivered from outside the TUI.

class

MCPServerInfo

Metadata for a configured MCP server and its tools.

class

RemoteAgent

Client that talks to a LangGraph server over HTTP+SSE.

Wraps langgraph.pregel.remote.RemoteGraph which handles SSE parsing, stream-mode negotiation (messages-tuple), namespace extraction, and interrupt detection. This class adds streamed message-object conversion for the Textual adapter and thread-ID normalization. State snapshots are returned as provided by the server.

class

ServerProcess

Manages a langgraph dev server subprocess.

Focuses on subprocess lifecycle (start, stop, restart) and health checking. Env-var management for restarts (e.g. configuration changes requiring a full restart) is handled by _scoped_env_overrides, keeping this class focused on process management.

class

ExtendedSkillMetadata

Extended skill metadata for CLI display, adds source tracking.

class

TextualUIAdapter

Adapter for rendering agent output to Textual widgets.

This adapter provides an abstraction layer between the agent execution and the Textual UI, allowing streaming output to be rendered as widgets.

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_children = False to prevent focus theft
Simple Static widgets for options
Standard message posting
Tool-specific widgets via renderer pattern

class

AskUserMenu

Interactive widget for asking the user questions.

Supports text input and multiple choice questions. Multiple choice questions always include an "Other" option for free-form input.

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 this message by running the suppress dispatch and calling NotificationCenterScreen.reload with the refreshed registry snapshot.

class

UpdateProgressScreen

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

class

QueuedMessage

Represents a queued user message awaiting processing.

class

ExternalInput

Textual message carrying an external prompt or command.

class

DeferredAction

An action deferred until the current busy state resolves.

class

TextualSessionState

Session state for the Textual app.

class

DeepAgentsApp

Main Textual application for deepagents-code.

class

AppResult

Result from running the Textual application.

Type Aliases

typeAlias

SpinnerStatus: Literal['Thinking', 'Offloading'] | None

Valid spinner display states, or None to hide.

typeAlias

AskUserWidgetResult

Discriminated union for the ask_user widget Future result.

Modules

module

theme

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.

View source on GitHub