agent-shell-queue.el — Persistent prompt queue for agent-shell

Overview

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

Installation

ELPAish Snapshot Repository

agent-shell-queue is also published as a development snapshot on ELPAish, a self-hosted, GPG-signed Emacs Lisp package archive. Add the snapshot stream to package-archives:

(add-to-list 'package-archives
             '("elpaish" . "https://tychoish.github.io/elpaish/snapshot/") t)
(package-refresh-contents)

You can install with package-install:

(package-install 'agent-shell-queue)

To verify package signatures, import the ELPAish signing key into package.el’s keyring and enable signature checking:

(url-copy-file "https://tychoish.github.io/elpaish/elpaish-keyring.gpg"
               "elpaish-keyring.gpg" t)
(package-import-keyring "elpaish-keyring.gpg")
(setq package-check-signature t)

use-package with VC

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)

Manual Installation

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)

You can also, with Emacs 29.1+, use package-vc-install to manage the dependency:

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

Configuration

Below is an example use-package configuration block mirroring typical production setups, using standard Emacs keybinding patterns without external keymap dependencies:

(use-package agent-shell-queue
  :ensure t
  :after agent-shell
  :defer t
  :commands (agent-shell-queue-buffer-open
             agent-shell-queue-capture
             agent-shell-prompt-menu
             agent-shell-prompt-select
             agent-shell-prompt-dispatch)
  :bind (("C-c q q" . agent-shell-queue-buffer-open)
         ("C-c q c" . agent-shell-queue-capture)
         ("C-c q m" . agent-shell-menu-dispatch))
  :config
  ;; Load prompt extensions
  (require 'agent-shell-prompt)
  (require 'agent-shell-prompt-menu)
  (require 'agent-shell-prompt-library)
  (require 'agent-shell-queue-org)

  ;; Serialization format ('org, 'json, 'yaml, or 'plist)
  (setq agent-shell-queue-serialization-format 'org)
  (setq agent-shell-queue-default-pause-delay 30.0)
  (setq agent-shell-queue-archive-enabled t)
  (setq agent-shell-queue-write-log-enabled t)

  ;; Backup & save hygiene
  (setq agent-shell-queue-safe-save t)
  (setq agent-shell-queue-safe-save-max-files 50)

  ;; UI & Display defaults
  (setq agent-shell-queue-pick-buffer-function #'agent-shell-menu--pick-buffer)
  (setq agent-shell-queue-show-ordinal-column nil)

  ;; Optional: Completion capf setup for capture and edit buffers
  (defun my/agent-shell-queue-completion-setup ()
    "Enable completion in queue capture buffers."
    (when (fboundp 'corfu-mode)
      (corfu-mode +1))
    (setq-local corfu-auto-prefix 2)
    (setq-local completion-at-point-functions
		(append '(cape-dabbrev agent-shell-queue-capture--slash-command-capf)
			(remq t completion-at-point-functions))))

  (add-hook 'agent-shell-queue-capture-mode-hook #'my/agent-shell-queue-completion-setup)
  (add-hook 'agent-shell-queue-edit-mode-hook #'my/agent-shell-queue-completion-setup))

Key Options & Customization

Serialization Format: agent-shell-queue-serialization-format controls queue persistence ('org, 'json, 'yaml, or 'plist).
SQLite Backend: To use SQLite instead of file serialization, call (agent-shell-queue-db-enable) or set agent-shell-queue-db-file.
Safe Save Backups: agent-shell-queue-safe-save enables versioned queue backups, capped by agent-shell-queue-safe-save-max-files.
Pause Delays: agent-shell-queue-default-pause-delay sets the pause duration (in seconds) inserted when pausing queue processing.
Archive Lifecycle: agent-shell-queue-archive-enabled enables archiving finished queue items to a JSONL file via agent-shell-queue-buffer-archive.

User Guides

Detailed use-case guides live under docs/:

API Reference

Detailed API documentation for all interactive commands, options, and functions is available in docs/api.org.

agent-shell-menu

Topic / Heading	Description
Session and Project Switching	Session mode selection and project switching commands
Actions and Commands	ACR-driven action selection, permission resolution, and commands
Content Insertion	Send files and buffers into active agent prompts
Output and Collapse Control	Toggle folding and collapse rules for agent responses
Session Diagnostics	View session state, model, and diagnostic mapping