A persistent prompt queue for agent-shell sessions, supporting multi-session dispatch with pause, resume, and archive lifecycle management. Queue state is serialized to plist, JSON, or YAML for session persistence across Emacs restarts. Interactive capture, edit, and item-view buffers allow queue manipulation without leaving Emacs. Fork operations split a queue across multiple sessions for parallel workloads.
This repository also includes agent-shell-menu.el: ACR-based transient menus
for navigating and controlling agent sessions, covering permission resolution,
action selection, command insertion, and collapse control. The menu requires
the queue and can be loaded separately with (require 'agent-shell-menu).
- Overview
- Installation
- API Reference
- Buffer/session management
- Permission resolution
- Action menu
- Project session switching
- Send content to agent shell
- Transient menus
- Command menu
- Collapse menu
- Session info buffer
- Variables
- Enable / disable
- Show state
- Export
- Import
- Org heading → queue capture
- Configuration
- Registries
- Data model
- Persistence — implementation in agent-shell-queue-persistence.el
- Queue operations
- Queue buffer
- Display configuration
- Item-view action table — single source of truth for keys, transient, and ACR menu
- Item raw inspect
- Transient predicates
- Display toggle commands
- Edit popup
- Capture buffer
- Entry points
- Raw edit mode
- Import
- Fork Queue Operations
- Interjection
- Queue-only mode
- License
Requires Emacs 29.1+. Run once to clone and register the package:
(package-vc-install '(agent-shell-queue
:url "https://github.com/tychoish/agent-shell-queue"))Requires Emacs 30+. Installs on first load if not already present:
(use-package agent-shell-queue
:vc (:url "https://github.com/tychoish/agent-shell-queue")
:after agent-shell)git clone https://github.com/tychoish/agent-shell-queue ~/.emacs.d/elpa/agent-shell-queue(use-package agent-shell-queue
:load-path "~/.emacs.d/elpa/agent-shell-queue"
:after agent-shell)git clone https://github.com/tychoish/agent-shell-queue ~/.emacs.d/elpa/agent-shell-queue(add-to-list 'load-path "~/.emacs.d/elpa/agent-shell-queue")
(require 'agent-shell-queue)Alist mapping label strings to commands for ‘agent-shell-select-action’. Each entry is either (LABEL . COMMAND) or (LABEL . (COMMAND . PREDICATE)). When a PREDICATE is supplied it is called with no arguments; the entry is omitted from the menu when the predicate returns nil.
Switch to an agent-shell buffer with status, cwd, context, and age annotations.
Resolve a pending permission prompt via ‘annotated-completing-read’.
Pick a common agent-shell action and run it via ‘call-interactively’. When a permission request is pending, permission responses are spliced into the menu.
Return live agent-shell buffers sharing the current buffer’s project directory.
Switch to another agent-shell session in the same project directory.
Prompt for a file and send it to the current agent-shell session. Uses ‘read-file-name’ for file selection, integrating with Consult/Vertico.
Pick a buffer and send its contents to the current agent-shell session. File-visiting buffers are sent as @file references; others as raw text.
no docstring
Insert one of the agent’s advertised ‘/’ commands at the prompt.
Pick a collapse action via ‘annotated-completing-read’. Offers bulk expand/collapse, per-category toggles, and entries to flip the three expand-by-default customization variables.
Display a read-only ephemeral buffer with live session diagnostics. Shows fragment count, agent uptime, queue options, queue depth, and the underlying shell process uptime for the current agent-shell buffer.
Path to the SQLite database file used by the queue DB backend. When nil, the path is derived from ‘user-emacs-directory’ as “agent-shell-queue.db”. Set before calling ‘agent-shell-queue-db-enable’ to store the database at a custom location.
Activate the SQLite persistence backend for agent-shell-queue. When DB-FILE is non-nil, use it as the database path; otherwise the default path under ‘user-emacs-directory’ is used (see ‘agent-shell-queue-db-file’). Sets ‘agent-shell-queue-save-function’, ‘agent-shell-queue-load-function’, and ‘agent-shell-queue-state-file-function’ to SQLite-aware variants. Saves the previous values so ‘agent-shell-queue-db-disable’ can restore them.
Deactivate the SQLite backend and revert to the previous persistence settings. Closes the database connection.
Display the SQLite database contents in a read-only popup buffer. Shows per-bucket item counts and a tabular dump of all persisted rows.
Export current queue items from SQLite to a YAML buffer. Loads current state from the DB then delegates to ‘agent-shell-queue-export’.
Import queue items from YAML into the SQLite database. SOURCE follows the same convention as ‘agent-shell-queue-import’: nil or ‘clipboard’ reads from the clipboard; ‘file’ prompts for a file. After importing, the DB is flushed immediately.
Capture the current org heading’s subtree text into the agent-shell-queue. Opens a queue capture buffer pre-seeded with the heading content. With prefix arg REMOVE-ORIGINAL, delete the original subtree immediately after opening the capture buffer.
Format used to persist queue state to disk. One of: ‘plist’ — s-expression with keyword-keyed plists (default; no extra deps) ‘json’ — JSON via built-in ‘json-serialize’/‘json-parse-string’ (Emacs 27+) ‘yaml’ — YAML via ‘yaml-encode’/‘yaml-parse-string’ from the ‘yaml’ package
When non-nil, called instead of the default file-based save logic. The function is called with no arguments and must persist the current queue items to a durable store. Used by backends such as ‘agent-shell-queue-db’ to bypass file I/O.
When non-nil, called instead of the default file-based load logic. The function is called with no arguments and must populate the queue items from a durable store. Used by backends such as ‘agent-shell-queue-db’ to bypass file I/O.
When non-nil, write a versioned backup before each queue state save. Backups are written to ‘agent-shell-queue-safe-save-directory’ using the format selected by ‘agent-shell-queue-safe-save-format’. Has no effect when ‘agent-shell-queue-save-function’ is set.
Directory for versioned queue backups written when ‘agent-shell-queue-safe-save’ is non-nil. Nil means use a subdirectory of ‘temporary-file-directory’ named “emacs-<instance>” where <instance> comes from ‘agent-shell-queue-instance-name’.
Serialization format for safe-save backups, or nil to use ‘agent-shell-queue-serialization-format’.
Instance identifier written into archive records. May be a string or a zero-argument function that returns a string. Defaults to the daemon name or system hostname. Override in config: (setq agent-shell-queue-instance-name “<name>”) (setq agent-shell-queue-instance-name ‘get-instance-name
File path for appending completed queue items as JSON lines. When nil (the default), completed items are not logged to disk.
When non-nil, completed items can be archived and ‘agent-shell-queue-buffer-archive’ is active. The destination path is controlled separately by ‘agent-shell-queue-archive-file-function’. Set to t to enable archiving.
Function returning the JSONL archive file path. Called with no arguments. Override to store the archive at a custom location. Only consulted when ‘agent-shell-queue-archive-enabled’ is non-nil.
Seconds between automatic queue flushes. Set to nil to disable.
Maximum entries retained in ‘agent-shell-queue–write-log’.
When non-nil, append each persistence event to agent-shell-queue-log and emit a message.
Display the in-memory write log in a readable buffer.
Instance identifier written into archive records. May be a string or a zero-argument function that returns a string. Defaults to the daemon name or system hostname. Override in config: (setq agent-shell-queue-instance-name “<name>”) (setq agent-shell-queue-instance-name ‘get-instance-name
Format used to persist queue state to disk. One of: ‘plist’ — s-expression with keyword-keyed plists (default; no extra deps) ‘json’ — JSON via built-in ‘json-serialize’/‘json-parse-string’ (Emacs 27+) ‘yaml’ — YAML via ‘yaml-encode’/‘yaml-parse-string’ from the ‘yaml’ package
Idle delay in seconds for the backup auto-send timer. Primary draining happens via ‘shell-maker-finish-output’ advice; this timer is only a safety net for buffers that become idle outside that path.
String prepended to prompts flagged for background sub-agent execution.
Command string sent when a clear item is dequeued.
File path for appending completed queue items as JSON lines. When nil (the default), completed items are not logged to disk.
Function returning the path to the queue state file.
Function called with a PROMPT string to pick an agent-shell buffer.
When non-nil, completed items can be archived and ‘agent-shell-queue-buffer-archive’ is active. The destination path is controlled separately by ‘agent-shell-queue-archive-file-function’. Set to t to enable archiving.
Function returning the JSONL archive file path. Called with no arguments. Override to store the archive at a custom location. Only consulted when ‘agent-shell-queue-archive-enabled’ is non-nil.
Maximum length (in characters) of captured response text to store. Responses longer than this are truncated with a “…[truncated]” suffix.
This prevents very large responses from bloating the queue state file. Set to nil to disable truncation and store full responses.
Default: 8192 (8KB) — balances completeness with file size.
Absolute maximum length (1MB) for response text, regardless of configuration. This hard limit prevents pathological cases from consuming excessive memory or creating unmanageable state files. Applies even when ‘agent-shell-queue-response-max-length’ is nil.
Seconds between automatic queue flushes. Set to nil to disable.
Hook run just before code and state are reloaded. Queue is paused and flushed to disk before this hook fires.
Hook run after code and state have been reloaded from disk.
When non-nil, called instead of the default file-based save logic. The function is called with no arguments and must persist the current queue items to a durable store. Used by backends such as ‘agent-shell-queue-db’ to bypass file I/O.
When non-nil, called instead of the default file-based load logic. The function is called with no arguments and must populate the queue items from a durable store. Used by backends such as ‘agent-shell-queue-db’ to bypass file I/O.
When non-nil, write a versioned backup before each queue state save. Backups are written to ‘agent-shell-queue-safe-save-directory’ using the format selected by ‘agent-shell-queue-safe-save-format’. Has no effect when ‘agent-shell-queue-save-function’ is set.
Directory for versioned queue backups written when ‘agent-shell-queue-safe-save’ is non-nil. Nil means use a subdirectory of ‘temporary-file-directory’ named “emacs-<instance>” where <instance> comes from ‘agent-shell-queue-instance-name’.
Serialization format for safe-save backups, or nil to use ‘agent-shell-queue-serialization-format’.
When non-nil, signal ‘user-error’ when no compatible live buffer exists. When nil (default), fall through to nil/unassigned assignment instead.
When non-nil in an agent-shell buffer, capture user-typed turns as queue items.
Current input routing mode for this agent-shell buffer. One of ‘default’ (normal shell input), ‘queue-intercept’ (capture user input as queue items while still submitting), or ‘queue-only’ (no prompt; all input routed through the queue). Set via ‘agent-shell-queue-set-input-mode’.
Reset all live agent-shell buffers in queue-intercept mode to default.
Session mode IDs that block queue dispatch. When a target shell is in one of these modes the item is not sent and the session queue is paused until the mode changes.
Archive the item at point to the archive file and remove it from the queue. Archiving must be enabled via ‘agent-shell-queue-archive-enabled’. The destination path is provided by ‘agent-shell-queue-archive-file-function’.
Open an Emacs Lisp capture buffer to compose a form for BUF’s queue. The capture buffer is in ‘emacs-lisp-mode’. Confirm with C-c C-c, cancel with C-c C-k. When dispatched, the form is evaluated via ‘eval’; errors are reported as messages and the item is marked done. BUF may be nil to enqueue to the unassigned bucket.
Enqueue an interactive COMMAND to run in Emacs for BUF’s queue. COMMAND is selected via ‘read-command’ (completing-read over all commands). When dispatched, the command is invoked with ‘call-interactively’. BUF may be nil to enqueue to the unassigned bucket.
Open a shell capture buffer to compose a command for eshell BUF. The capture buffer is in ‘sh-mode’. Confirm with C-c C-c. BUF may be nil to enqueue to the unassigned bucket.
Open a shell capture buffer to compose a command for eat BUF. The capture buffer is in ‘sh-mode’. Confirm with C-c C-c. BUF may be nil to enqueue to the unassigned bucket.
Hook run when a queue item transitions to done status. Each function is called with two arguments: BUF-NAME and ITEM.
Force-save queue state to disk immediately.
Pause, flush, reload source code, and reload state from disk. Stops the idle timer, drops all turn-complete subscriptions, reloads ‘agent-shell-queue.el’ from source, re-reads queue state from disk, and reinstates subscriptions for buffers with active/running items. Queue remains paused after reload; call ‘agent-shell-queue-resume’ when ready.
Remove items whose struct fields cannot be read; print each to Messages. Useful after a code reload that left in-memory structs with mismatched layouts. When called interactively, prompts y/n/a for each candidate before removing it. Affected buffer queues are paused and the queue state is saved.
Display the on-disk queue state file in a read-only popup buffer.
Show the Buffer column in the queue buffer. Toggle interactively with ‘agent-shell-queue-toggle-buffer-column’ (db in the menu).
Show the ordinal (#) column in the queue buffer.
Show the Age column in the queue buffer.
Show the Kind column in the queue buffer.
Display prompt on a second line with a separator between items. When non-nil, ‘<down>’ and ‘<up>’ move by item rather than by line.
Narrow the queue buffer view: choose global, a directory, or a specific buffer.
Reset the queue buffer to the global scope (show all items).
Export items in the current scope to a read-only YAML buffer. Multi-line prompt and response fields are formatted as YAML literal block scalars.
Keymap for ‘agent-shell-queue-mode’.
Insert a pause item into BUF’s queue, optionally at 1-based POSITION. When called interactively, prompts for the target buffer.
Insert a context-drop item with PROMPT into BUF’s queue. When called interactively, prompts for target buffer and context text.
Insert a wait-until item into BUF’s queue. Prompts for a target date/time; uses ‘org-read-date’ when available, otherwise reads a string parseable by ‘date-to-time’ (e.g. “2026-05-16 14:30”). When dispatched the item blocks the queue until the target time is reached, then marks itself done and advances to the next item automatically.
Keymap for ‘agent-shell-queue-item-view-mode’.
Archive the N oldest done items across all queues. Errors if archiving is not enabled.
Archive all done items across all queues. Errors if archiving is not enabled or no done items exist.
Toggle ‘agent-shell-queue-archive-enabled’ and report the new state.
Import items from the JSONL archive file into the queue as active items. FILE defaults to the path returned by ‘agent-shell-queue-archive-file-function’; when called interactively with a prefix argument, prompts for a file path.
Keymap for ‘agent-shell-queue-inspect-mode’.
Open a read-only raw-serialization view of the queue item at point. Prompts for the serialization format (p=plist j=json y=yaml in the buffer).
Open a raw-serialization view of the item shown in this buffer. Prompts for the serialization format (p=plist j=json y=yaml in the buffer).
Open (or refresh) the agent-shell-queue buffer.
Switch to the agent-shell-queue buffer in the current window.
Open a capture buffer targeting BUF (nil adds to the unassigned queue). When called interactively from an agent-shell buffer, targets that buffer. With a prefix argument, opens an unassigned capture instead.
Pick column display options via ‘annotated-completing-read’. Offers bulk presets, per-column visibility toggles, and the multi-line format switch. Changes take effect immediately via ‘agent-shell-queue-buffer-refresh’.
Keymap for ‘agent-shell-queue-edit-mode’.
Edit a queued item’s prompt. In ‘agent-shell-queue-mode’ without SELECT (prefix argument): edit the item at point immediately. With SELECT, or when point carries no item, or when called from outside ‘agent-shell-queue-mode’: select via annotated-completing-read. Candidates include all non-done, non-running items across all buffers.
Keymap for ‘agent-shell-queue-capture-mode’.
Queue PROMPT for BUF, optionally flagged for BACKGROUND sub-agent execution. Send immediately if BUF is idle, otherwise store in the queue. When called interactively, opens a capture buffer for composing the prompt.
Enqueue a clear command for BUF. Uses ‘agent-shell-queue-clear-command’ as the prompt.
Open a capture buffer to compose a prompt for the unassigned queue. Unassigned items display in blue and can later be assigned to a shell via ‘t’.
Open a capture buffer pre-seeded with the active region text. When no region is active, opens an empty capture. BUF is the target agent-shell buffer; nil adds to the unassigned queue.
Open a capture buffer pre-seeded with a string selected from context. Candidates include thing-at-point, the active region, the current line, and the kill ring. BUF is the target agent-shell buffer; nil for the unassigned queue.
Open a capture buffer pre-seeded with the current clipboard contents. BUF is the target agent-shell buffer; nil adds to the unassigned queue.
Keymap for ‘agent-shell-queue-raw-edit-mode’.
Open the queue for direct YAML editing. The queue is paused while the edit buffer is live. Confirm changes with M-x agent-shell-queue-raw-edit-confirm; cancel with M-x agent-shell-queue-raw-edit-cancel.
Import queue items from YAML. With no prefix arg reads from clipboard; with prefix arg prompts for a file. For each item whose ID already exists, prompts to keep, replace, or assign new ID.
Default mode for creating new sessions when forking a queue. ‘new’ creates a clean new session via ‘agent-shell-new-shell’. ‘fork’ uses the ACP fork session option via ‘agent-shell-fork’.
Fork the queue for SOURCE-BUF starting at FROM-ID into a new agent-shell session.
Items at or after FROM-ID (by queue position among active/deferred/draft items) are moved to the new session. When FROM-ID is nil, all eligible items are moved. The original session is paused during session creation.
OPTS is a plist with these keys: :fork-mode Symbol ‘new’ (default) or ‘fork’ — how to create the new session. ‘new’ calls ‘agent-shell-new-shell’; ‘fork’ calls ‘agent-shell-fork’. :use-worktree Non-nil — create a git worktree for the new session. :worktree-path String — explicit worktree path (auto-generated when nil). :worktree-branch String — new branch name for the worktree. :capture-pending Non-nil — mark items at/after FROM-ID as ‘pending-fork’ in the original session instead of moving them, then leave the session paused so new items can be inserted before the frozen ones.
Release all pending-fork items in BUF back to active status and resume dispatch. BUF defaults to the current agent-shell session when called from one.
Insert a fork task into BUF’s queue immediately before ITEM-ID. When ITEM-ID is nil, appends to the end of the queue. When the fork task is dispatched (as an emacs item), it forks the queue starting at the item that follows the fork task in the queue at dispatch time. OPTS is the fork options plist (see ‘agent-shell-queue-fork-session’).
Insert a fork task into BUF’s queue immediately after ITEM-ID. When ITEM-ID is nil, appends to the end of the queue. When the fork task is dispatched, it forks the queue starting at the next item after the fork task (determined dynamically at dispatch time). OPTS is the fork options plist (see ‘agent-shell-queue-fork-session’).
Fork the queue starting at the item at point into a new session. Prompts interactively for fork options; uses annotated-completing-read when called outside the queue buffer to build options without task-at-point context.
Insert a fork queue item before the item at point. Prompts for fork options interactively.
Insert a fork queue item after the item at point. Prompts for fork options interactively.
Text appended to the interjection prompt before sending. Set to nil to send the user’s text verbatim without a continuation instruction.
Keymap for ‘agent-shell-queue-interjection-mode’.
Default input routing mode for new agent-shell sessions. One of ‘default’ (normal shell input), ‘queue-intercept’ (capture user input as queue items while still submitting), or ‘queue-only’ (no prompt; all input routed through the queue). Use ‘agent-shell-queue-set-input-mode-default’ to change this and sync all existing sessions simultaneously.
Set ‘agent-shell-queue-input-mode-default’ to MODE and sync all existing sessions. MODE is prompted interactively from the three valid options. All live agent-shell buffers are immediately updated to the new default.
Reset all live agent-shell buffers to default input mode.
Toggle queue-intercept as the default input mode and sync all sessions.
Toggle queue-only as the default input mode and sync all sessions.
Clear the ready overlay and open the queue enqueue dispatch menu. Any keypress in queue-only mode at the idle prompt routes here, giving access to all registered item kinds rather than prompt-only capture.
Route all agent-shell input through the queue; show <ready> when idle.
This is a minor mode. If called interactively, toggle the ‘Agent-Shell-Queue-Only mode’ mode. If the prefix argument is positive, enable the mode, and if it is zero or negative, disable the mode.
If called from Lisp, toggle the mode if ARG is ‘toggle’. Enable the mode if ARG is nil, omitted, or is a positive number. Disable the mode if ARG is a negative number.
To check whether the minor mode is enabled in the current buffer, evaluate the variable ‘agent-shell-queue-only-mode’.
The mode’s hook is called both when the mode is enabled and when it is disabled.
Key Binding
RET agent-shell-queue-ready-capture SPC agent-shell-queue-ready-capture
<remap> <self-insert-command> agent-shell-queue-ready-capture
Copyright (C) tychoish. GPL-3.0 or later. See the source file header for the full license text.