sessions

Fallback maximum number of recent threads to load and display.

Accepted internal output modes for CLI subcommands.

Create a state directory and restrict it to its owner.

The state directory holds sessions.db and history.jsonl, which hold full conversation content and are written with the default file mode. The directory permissions are the only thing that keeps another local user out, so every creator must go through this function rather than a bare mkdir.

Return whether a message is hidden from user-facing session history.

Format ISO timestamp for display (e.g., 'dec 05, 6:10pm').

Format ISO timestamp as relative time (e.g., '5m ago', '2h ago').

Format a filesystem path for display.

Paths under the user's home directory are shown relative to ~. All other paths are returned as-is.

Get path to global database.

The result is cached after the first successful call to avoid repeated filesystem operations.

Generate a new thread ID as a full UUID7 string.

List threads from checkpoints table.

Populate checkpoint-derived fields for an existing thread list.

This is used by the /threads modal to enrich rows in one background pass, so the latest checkpoint is fetched and deserialized at most once per row.

Prewarm thread selector cache for faster /threads open.

Fetches a bounded list of recent threads and populates checkpoint-derived fields for currently visible columns into the in-memory cache. Intended to run in a background worker during app startup and again whenever the session database has changed (e.g. after a turn writes new checkpoints), so the selector's first paint is never missing a thread the user just created.

Re-running this is cheap: the per-thread message-count and initial-prompt caches are keyed on checkpoint freshness, so only threads whose latest checkpoint changed are read back from disk.

Get cached recent threads, if available.

Apply cached message counts onto thread rows when freshness matches.

Apply cached initial prompts onto thread rows when freshness matches.

Get the most recent thread, optionally agent-filtered and/or excluding a thread.

List distinct threads in checkpoint recency order, optionally agent-filtered.

Get the latest stored update timestamp for a thread.

Advance local discovery metadata after reading remote model activity.

Only the latest root checkpoint is updated, preserving historical metadata and any newer timestamp already written by a shared server checkpointer. Preserve its original timestamp separately so a lone discovery seed keeps its creation time as remote activity advances.

Get agent_name for a thread.

Get the most recently stored cwd for a thread.

Check if a thread exists in checkpoints.

Find threads whose IDs start with the given prefix.

Validate a thread name.

Read a thread's durable name independently of checkpoint revisions.

Atomically name an existing thread without mutating its conversation.

Delete thread checkpoints, side-question costs, and offloaded history.

Removes the thread's checkpoint/write rows, then makes a best-effort attempt to remove the per-thread compaction archive and handoff snapshots under ~/.deepagents (local mode) so deletion does not leave orphaned history behind. History cleanup failures are logged, not raised, and do not affect the return value, which reflects only whether checkpoint rows were removed.

Get a checkpointer requiring live thread ownership for database writes.

Index a remote handoff locally with its initial summary and resume metadata.

Only seed an absent thread; never replace shared server checkpoints. Thread history still loads from the connected agent, so subsequent remote turns take precedence over this discovery snapshot. Reserve the local thread for the save when this process does not already own it.

Persist discovery and resume metadata on a newly checkpointed thread.

The remote state-update API does not forward config metadata. Stamp the saved checkpoints before exposing a newly seeded thread to the user.

Read the thread listing limit from the environment.

CLI handler for deepagents threads list.

Fetches and displays a table of recent conversation threads, optionally filtered by agent name, git branch, or working directory.

CLI handler for: deepagents threads delete.

Thread metadata returned by list_threads.