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).
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)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-injson-serialize~/~json-parse-string(Emacs 27+)yaml— YAML viayaml-encode~/~yaml-parse-stringfrom theyamlpackage
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. Default: 60.0.
String prepended to prompts flagged for background sub-agent execution.
Default: "/background ".
When non-nil, path to an append-only JSONL file where completed items are logged. Useful for audit trails across sessions.
When non-nil, items reaching done status are archived rather than discarded.
Hooks run immediately before and after reloading queue state from disk.
Pause the global queue; no new items will be dispatched.
Resume the global queue after being paused.
Resume all session-level pauses in addition to any global pause.
Pause dispatch for a specific session buffer BUF (default: current buffer).
Resume dispatch for a specific session buffer BUF.
Toggle intercept mode for BUF. When active, shell-maker-submit is
intercepted and prompts are routed through the queue rather than sent directly.
Add a new active item with PROMPT as the args payload, destined for BUF.
When BACKGROUND is non-nil, the item is flagged for sub-agent execution.
Saves and refreshes.
Add a prompt to the unassigned bucket (not yet assigned to any session).
Enqueue a Lisp form to be eval-ed when the queue dispatches to BUF.
Remove item ID from the queue.
Move item ID to deferred status; it will not be dispatched automatically.
Replace the args text of item ID with NEW-PROMPT.
Reorder item ID within its bucket.
Mark item ID as done, optionally archiving it if archiving is enabled.
Dispatch item ID to its assigned session immediately. If the item has a
non-nil executor, the executor is called instead of the built-in kind
dispatch, and the session-mode-blocked check is skipped. See the
Executor Interface section for details.
Queue PROMPT for BUF, optionally flagged for BACKGROUND sub-agent execution. Sends immediately if BUF is idle; otherwise stores in the queue. When called interactively, opens a capture buffer for composing the prompt.
Open a capture buffer targeting BUF. When called interactively from an agent-shell buffer, targets that buffer. With a prefix argument, opens an unassigned capture instead.
Open a capture buffer targeting the unassigned queue bucket.
Create a queue item from the active region content.
Create a queue item from context-at-point candidates (thing-at-point, kill ring, current line).
Create a queue item from the current clipboard/kill-ring contents.
Force-save queue state to disk immediately.
Reload queue state from disk, replacing the in-memory state.
Register a custom serialization format FMT with SERIALIZE-FN and DESERIALIZE-FN. Use this to add support for new storage backends.
Serialize STORE to a string using the configured format.
Deserialize STRING into STORE using the configured format.
Export the current queue to a file.
Archive done items from the current buffer’s queue bucket.
Open (or refresh) the *agent-shell-queue* view buffer.
Interactively set the scope for the queue view (current buffer, project, global).
Widen the queue view to show all sessions globally.
Display the raw on-disk queue state in a temporary buffer.
agent-shell-menu.el provides ACR-based interactive menus for agent-shell
sessions. Load it with (require 'agent-shell-menu) after the queue.
Main transient prefix covering session management, queue operations, capture, intercept mode, interjection, and permission resolution. Bind to a key:
(keymap-global-set "C-c a" #'agent-shell-dispatch)Switch to an agent-shell buffer with status, cwd, context, and age annotations.
Pick a common agent-shell action and run it via annotated-completing-read.
Permission responses are spliced into the menu when a permission prompt is active.
Resolve a pending permission prompt via annotated-completing-read.
Insert one of the agent’s advertised / commands at the prompt.
Pick a collapse action: bulk expand/collapse, per-category toggles, and flip the three expand-by-default customization variables.
Configurable alist mapping display names to command symbols for
agent-shell-select-action. Extend to add custom actions:
(add-to-list 'agent-shell-action-alist '("my custom action" . my-custom-command))agent-shell-queue-db.el provides a SQLite persistence backend. Load it and
call (agent-shell-queue-db-enable) to activate.
agent-shell-queue-org.el provides an Org-mode serialization format, where
top-level headings are queue buckets and second-level headings are items.
Copyright (C) tychoish. GPL-3.0 or later. See the source file header for the full license text.