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.
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-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.