agent-shell-sessions

agent-shell-sessions is an Emacs package for discovering and resuming coding-agent sessions from the agents' native local state. It does not depend on agent-shell transcripts, so it can find sessions created in a terminal, an IDE, or another Emacs integration.

Why this exists

agent-shell already has good session support. It can ask the selected agent over ACP for its sessions, choose a new/latest/existing session, resume or load it, and optionally replay prior messages. This package does not replace any of that. It supplies the part agent-shell does not aim to be: one searchable session index across agents and projects, populated from the agents' native state before an ACP process is started.

Concern	Regular agent-shell	agent-shell-sessions
Discovery source	The selected agent's ACP session/list response	Read-only adapters for each CLI's native local state
Scope of one picker	One selected agent, normally scoped by the current working directory	Every enabled provider and every discovered project
Sessions created outside Emacs	Visible when that ACP implementation lists them	Visible whenever the native-state adapter can read them
Agent support required for discovery	The ACP server must advertise and implement session listing	No ACP listing support is needed
Selection UI	agent-shell's session prompt	Consult search over provider, age, title, directory, and native ID
Resume and conversation UI	Owned by agent-shell	Delegated back to agent-shell after selection
History replay	Supported by agent-shell when the agent supports session/load	Not reimplemented; agent-shell still controls it
Stability	Uses the public ACP contract	Native formats are private and may require adapter updates

Use this package when you regularly switch between Codex, Claude, Cursor, or other agents; start sessions outside Emacs; work across many repositories; or have an ACP implementation whose session listing is missing or incomplete. If agent-shell's existing picker already shows every session you need for one agent and project, this package adds little beyond Consult search and a programmatic normalized session API.

Discovery without session/list does not guarantee resumability: the selected agent must still be able to resume or load the native ID through agent-shell. This package deliberately leaves authentication, ACP lifecycle, message replay, rendering, and conversation management to agent-shell.

See agent-shell's session configuration for its native new, latest, and prompt strategies and restore-verbosity options.

The package currently supports:

Provider	Native discovery source	Native resume command
Codex	$CODEX_HOME/state_*.sqlite, table threads	codex resume -C DIR ID
Claude Code	$CLAUDE_CONFIG_DIR/projects/**/*.jsonl	claude --resume ID
Cursor Agent CLI	CURSOR_CONFIG_DIR/chats/*/*/store.db	agent --resume ID

Provider files are only read. SQLite databases are queried exclusively with SELECT and PRAGMA statements. Automatic backend selection uses an explicit read-only Emacs connection when supported, otherwise sqlite3 -readonly when available. Older Emacs builds without either facility still issue no write SQL.

Status

This is an early standalone release. Its normalized session and provider APIs are intended to remain stable, but additional native providers and real-world format fixtures are still needed.

The native file formats are not stable public APIs. Each provider is isolated behind an adapter so schema changes do not affect the normalized package API.

Installation

Install directly from GitHub with Emacs 29's package-vc support:

(package-vc-install
 '(agent-shell-sessions
   :url "https://github.com/guibor/agent-shell-sessions"))

Consult and agent-shell must be available from a configured package archive; both are published on MELPA.

For local development, clone the repository, add it to load-path, and require the package:

(add-to-list 'load-path "/path/to/agent-shell-sessions")
(require 'agent-shell-sessions)

Consult and agent-shell are required runtime dependencies. Installing this as an Emacs package installs their package dependencies as well. Consult remains compatible with completion frontends such as Vertico, but this package does not force a particular completion stack.

Emacs 29.1 or newer is required. On Emacs builds without native SQLite support, the sqlite3 executable is required for Codex and Cursor discovery.

Commands

• M-x agent-shell-sessions-resume: select a session and resume it in agent-shell.
• C-u M-x agent-shell-sessions-resume: restrict selection to the current directory.
• M-x agent-shell-sessions-resume-native: explicitly resume in the provider's native terminal client.
• M-x agent-shell-sessions-copy-resume-command: copy a shell-safe native command.
• M-x agent-shell-sessions-copy-id: copy the provider's native session ID.
• M-x agent-shell-sessions-check-provider: refresh and validate one adapter.
• M-x agent-shell-sessions-clear-cache: force the next picker to rescan native state.

The agent-shell command discovers sessions itself, then resolves the matching provider from ordinary agent-shell-agent-configs. It does not change the preferred agent, authentication, command, or global agent-shell configuration.

Native argv remains available programmatically through agent-shell-sessions-command-spec.

Public API

(agent-shell-sessions-list)
(agent-shell-sessions-list :providers '(codex claude) :limit 20)
(agent-shell-sessions-list :cwd default-directory)
(agent-shell-sessions-command-spec session)

Every provider returns an agent-shell-sessions-session with these fields:

• provider: stable provider symbol.
• id: native resumable session identifier.
• title: best native title or first user prompt.
• cwd: native working directory when recoverable.
• created-at and updated-at: Emacs time values.
• source-path: provider-owned source file.
• metadata: provider-specific information that does not belong in the core API.

Discovery results are cached for ten seconds by default so repeated completion actions do not rescan large histories. Customize agent-shell-sessions-cache-seconds or call agent-shell-sessions-clear-cache when immediate refresh is required.

Third-party adapters use the same declarative registry as the built-in providers:

(agent-shell-sessions-define-provider example
 :label "Example"
 :discover-function #'example-discover-sessions
 :agent-shell-identifier 'example-agent)

Construct records with agent-shell-sessions-make-session. Native terminal commands are optional; agent-shell resume only requires discovery and a matching agent-shell identifier. Loaded adapters are enabled automatically unless agent-shell-sessions-enabled-providers is set to an explicit allowlist.

The complete contract, Pi and Kiro examples, validation workflow, and a copyable JSON adapter are in docs/provider-authoring.org.

Provider notes

Codex discovery treats the newest state_*.sqlite file as authoritative and uses session_index.jsonl only as supplementary title metadata. The SQL is assembled from the actual threads schema, allowing optional columns to be absent. Archived, scheduler, and subagent/approval-review threads are hidden by default; each category has a corresponding agent-shell-sessions-codex-include-* option.

Claude discovery reads bounded head and tail portions of large JSONL files. It extracts native IDs, directories, timestamps, titles, and the first user message while avoiding loading an entire multi-gigabyte transcript merely to build a picker.

Cursor support currently targets Cursor Agent CLI/ACP sessions, not the Cursor desktop Composer database. It reads the hex-encoded metadata row in each store.db and the optional sibling meta.json; it does not reverse-engineer the content-addressed protobuf blob graph.

Tests

The ERT suite creates disposable native-format fixtures:

emacs -Q --batch \
  -L . -L tests \
  -l tests/agent-shell-sessions-tests.el \
  -f ert-run-tests-batch-and-exit

SQLite fixture tests require the sqlite3 executable. Runtime discovery can instead use Emacs built-in SQLite support.

License

GPL-3.0-or-later.