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
- Session mode selection
- Permission resolution
- Action menu
- Project session switching
- Send content to agent shell
- Command menu
- Collapse menu
- Session info buffer
- Variables
- Enable / disable
- Show state
- Export
- Import
- Org heading → queue capture
- Backup restore
- 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
- Capture buffers
- 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-menu-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.
(fn &optional ON-SUCCESS)
Select a session mode via ‘annotated-completing-read’, annotating the current one. Like ‘agent-shell-set-session-mode’ but annotates each candidate with its description (the same text shown at the start of an agent-shell session) and marks the active mode as “[current]”, instead of requiring the user to already know the candidate list. Unlike ‘agent-shell-cycle-session-mode’ this prompts instead of blindly advancing to the next mode.
Optionally, get notified of completion with ON-SUCCESS function.
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.
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, entries to flip the three expand-by-default customization variables globally, and a buffer-local variant that only changes the default for this session.
Keymap for agent-shell info help buffers. Inherits ‘help-mode-map’ once loaded.
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.
(fn &optional DB-FILE)
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’.
(fn &optional SOURCE)
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.
(fn &optional REMOVE-ORIGINAL)
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 number of versioned backup files to keep in the safe-save directory. When non-nil and the backup count exceeds this limit, the oldest file is deleted after each save — one file at a time so lowering the limit converges gradually. Requires ‘agent-shell-queue-safe-save’.
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.
Restore queue items from a versioned backup via annotated-completing-read. Lists backup files in the safe-save directory newest-first. Only items whose item-id is not already present in the live queue are added, so the operation is safe to run against an active queue. Saves and refreshes after merging.
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
Default pause duration in seconds after one task completes before the next task runs. Set to 0 or nil for no delay.
When non-nil, send an alert notification when a task pause or delay starts. The notification message includes the duration of the pause.
Duration in seconds before a pause ends to send an alert notification. When non-nil and less than the total pause duration, an alert is sent when ‘(total-pause-duration - alert-before-pause-end)‘ seconds elapses.
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.
Alists of symbols mapping ‘<agent-shell-identifier>‘ to background command prefix string, or a function/value.
Alists of symbols mapping ‘<agent-shell-identifier>‘ to clear command string, or a function/value.
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’.
Maximum number of versioned backup files to keep in the safe-save directory. When non-nil and the backup count exceeds this limit, the oldest file is deleted after each save — one file at a time so lowering the limit converges gradually. Requires ‘agent-shell-queue-safe-save’.
Seconds of Emacs idle time after which the queue state is flushed to disk. Set to nil to disable idle-triggered saves (default).
Seconds after dispatch before a still-running item is reported as stalled. The ACP/shell-maker layer has no watchdog of its own: a wedged Lisp event loop or a desynced busy flag leaves a dispatched item showing ‘running’ with no further user-visible feedback, indefinitely. This is a one-shot check, not a retry loop — it only surfaces the condition via ‘alert’, it does not cancel or resend the item. Set to nil to disable.
When non-nil, signal ‘user-error’ when no compatible live buffer exists. When nil (default), fall through to nil/unassigned assignment instead.
Pause dispatch for every known session (batch ‘agent-shell-queue-session-pause’).
Resume dispatch for every known session. Alias for ‘agent-shell-queue-unpause-all-sessions’.
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’.
(fn PROMPT DIR &optional BACKGROUND)
Add a new active item for PROMPT destined for directory queue DIR. Save and refresh.
(fn DIR)
Open a capture buffer for directory queue DIR.
(fn BUF)
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.
(fn COMMAND BUF)
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.
(fn BUF)
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.
(fn BUF)
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. Every known session is paused before reload — the session-paused list survives the reload (it lives on ‘agent-shell-queue–queue’, which ‘defvar’ does not reset) — so nothing dispatches until ‘agent-shell-queue-resume’ is called.
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’.
(fn &optional BUF POSITION DURATION)
Insert a pause item into BUF’s queue, optionally at 1-based POSITION. If DURATION is specified (number of seconds), the pause auto-resumes after DURATION seconds. When called interactively, prompts for target buffer (and duration with prefix arg).
(fn PROMPT &optional BUF)
Insert a context-drop item with PROMPT into BUF’s queue. When called interactively, prompts for target buffer and context text.
(fn BUF)
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’.
(fn N)
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.
(fn &optional FILE)
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.
(fn &optional BUF)
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’.
(fn &optional SELECT)
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’.
(fn PROMPT &optional BUF BACKGROUND DELAY-BEFORE DELAY-AFTER)
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. Optional DELAY-BEFORE and DELAY-AFTER specify per-task pre-dispatch and post-completion delays.
(fn &optional BUF)
Enqueue a clear command for BUF. Uses the resolved clear command for BUF 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’.
(fn &optional BUF)
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.
(fn &optional BUF)
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.
(fn &optional BUF)
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. Every session not already paused 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.
(fn &optional SOURCE)
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’.
(fn SOURCE-BUF &optional FROM-ID OPTS)
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.
(fn &optional BUF)
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.
(fn BUF &optional ITEM-ID OPTS)
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’).
(fn BUF &optional ITEM-ID OPTS)
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.
(fn MODE)
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.
(fn &optional ARG)
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.