API documentation for the entire agent-shell-queue package, generated from docstrings.
Select a session mode via annotated-completing-read. 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.
Return live agent-shell buffers sharing the current buffer’s project directory.
Switch to another agent-shell session in the same project directory.
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.
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.
Resolve a pending permission prompt via annotated-completing-read.
Insert one of the agent’s advertised / commands at the prompt.
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.
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.
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.
Define ‘agent-shell-menu-output-key-KEY’ and bind it in agent-shell-mode-map. In the output area, or while the shell is busy, calls FN interactively. Self-inserts KEY only when at the idle prompt, unless queue-only mode is active (in which case routes to agent-shell-queue-ready-capture instead). Also binds FN directly in agent-shell-viewport-view-mode-map.
Start a new agent-shell session in DIR.
agent-shell operations — navigate, act, send, queue, and session management.
Enqueue and capture operations for the current agent-shell session. Bound to “e” in agent-shell-mode-map; self-inserts at the idle prompt.
Keymap for agent-shell-queue-mode.
no docstring
no docstring
no docstring
no docstring
no docstring
Evaluate BODY inside the queue load/save/refresh lifecycle. Ensures the queue is loaded before BODY runs, then persists state and refreshes the queue display after BODY completes. Returns the value of BODY’s last form. Does not protect against errors — if BODY signals, the save and refresh are skipped.
Register EXECUTOR (and optional CAPTURE and CREATE) under NAME. NAME may be a string or symbol; it is coerced to a string. Re-registering an existing name replaces the entry. The name is written into serialized queue state, so it must be stable across Emacs restarts. CREATE, when provided, is a zero-arg function called by agent-shell-queue-buffer-open-shell when the associated buffer is dead; it should create and return a new buffer of the same type. Returns EXECUTOR.
(fn &key KIND LABEL BUFFER-PRED DISPATCH-FN INPUT-SPEC)
Register item type with KIND, LABEL, BUFFER-PRED, DISPATCH-FN, and INPUT-SPEC. KIND is a symbol; re-registering an existing KIND replaces the entry.
Return non-nil when the current buffer’s session queue dispatch is paused.
Keymap for agent-shell-queue-capture-mode.
Mode for composing a queued agent-shell prompt.
Key Binding
C-c C-b agent-shell-queue-capture-enable-background-task C-c C-c agent-shell-queue-capture-confirm C-c C-f agent-shell-queue-insert-file C-c C-k agent-shell-queue-capture-cancel C-c C-p agent-shell-queue-capture-insert-thing-at-point C-c C-s agent-shell-queue-capture-save-draft C-c C-x agent-shell-queue-capture-select-context C-c C-y agent-shell-queue-capture-yank-kill
C-c M-b agent-shell-queue-capture-disable-background-task C-c M-f agent-shell-queue-insert-buffer C-c M-w agent-shell-queue-capture-yank-clipboard
In addition to any hooks its parent mode markdown-mode might have run, this mode runs the hook agent-shell-queue-capture-mode-hook, as the final or penultimate step during initialization.
Confirm capture: queue the buffer contents and close.
Discard the capture buffer without queuing.
Save capture buffer contents as a draft queue item without closing. The item is stored with ‘draft’ status and skipped by dispatch. If a draft was previously saved from this buffer it is updated in place.
Flag this capture for background sub-agent execution.
Clear the background sub-agent flag from this capture.
Insert the most recent kill-ring entry at point.
Insert the current clipboard contents at point.
Insert the thing at point from the buffer that opened this capture.
Select a string from origin buffer context via ACR and insert it.
Prompt for a file and insert its contents at point. Works in both capture and edit buffers.
Pick a buffer and insert its entire contents at point. Works in both capture and edit buffers.
Open a capture buffer targeting BUF (nil add to the unassigned queue). When called interactively from an agent-shell buffer, targets that buffer. With a prefix argument, opens an unassigned capture instead.
Queue PROMPT for BUF, optionally flagged for BACKGROUND execution. Send immediately if BUF is idle and no DELAY-BEFORE is set, otherwise store in the queue. When called interactively, opens a capture buffer for composing the prompt. Optional DELAY-BEFORE and DELAY-AFTER specify pre-dispatch and post-completion delays in seconds.
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 key t.
Open a capture buffer for an item to be inserted after the item at point. The confirmed item is spliced into the queue immediately after the current row, rather than appended to the end.
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, active region, current line, and kill ring. BUF is the target buffer; nil for 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.
Add a new active item for PROMPT in directory queue DIR. Optional BACKGROUND, DELAY-BEFORE, and DELAY-AFTER configure task settings.
Open a capture buffer for directory queue DIR.
Open an Emacs Lisp capture buffer to compose a form for BUF’s queue. The capture buffer is in emacs-lisp-mode. Confirm with M-x agent-shell-queue-capture-confirm, cancel with M-x agent-shell-queue-capture-cancel. 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 M-x agent-shell-queue-capture-confirm. 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 M-x agent-shell-queue-capture-confirm. BUF may be nil to enqueue to the unassigned bucket.
Pause dispatch for every known session (batch session-pause).
Resume dispatch for every known session. Alias for agent-shell-queue-unpause-all-sessions.
Pause dispatch for BUF (default: current agent-shell session).
Resume dispatch for BUF (default: current agent-shell session). Any running ‘pause’ or ‘compact’ item for BUF is marked done automatically.
Interrupt stuck shell BUF and auto-resume queue dispatch when it becomes idle. Marks any running item as aborted, sends an interrupt to the shell, then polls until the shell is no longer busy before resuming dispatch. Use this when the shell is frozen with no prompt appearing after the last turn.
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.
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.
Return (BUF-NAME . ITEM) for the queue item with ID, or nil. Ensures the queue is loaded before searching. Public API wrapper around the internal agent-shell-queue--item-by-id.
Interactively pick a queue item and return its (BUF-NAME . ITEM) pair. Uses annotated-completing-read with item IDs and prompts as annotations. PROMPT overrides the default completion prompt. Useful for debugging.
Add a new active item for PROMPT destined for BUF. Save and refresh. When BACKGROUND is non-nil the item is flagged for sub-agent execution. Optional DELAY-BEFORE and DELAY-AFTER specify per-task pre-dispatch and post-completion delays in seconds. Registers a ‘turn-complete’ subscription on BUF if one is not already active.
Add a new item for PROMPT to the unassigned bucket. Optional BACKGROUND, DELAY-BEFORE, and DELAY-AFTER configure task settings. Unassigned items display in blue and sort after all shell-assigned items.
Remove the item with ID from the queue. Save. Drops the ‘turn-complete’ subscription for any bucket that becomes empty. Cancels any pending wait timer for the item. Always logs the removed item’s prompt to Messages.
Toggle status of item ID between active and ‘blocked.skip’. Save.
Unblock item ID: set blocked.task/blocked.skip to active. For blocked.task, cascades active to subsequent blocked.dep items.
Replace the args of item ID with NEW-PROMPT. Save.
Set the background flag of item ID to FLAG. Save.
Move item ID one position earlier in its buffer’s queue.
Move item ID one position later in its buffer’s queue.
Send item with ID to target buffer, marking it as running. Items flagged as background are wrapped with agent-shell-queue-background-prefix. The item transitions to done when the buffer’s turn-complete event fires. Running and done items are not persisted across sessions. If the item has a non-nil executor field, it is called as (funcall executor item args) instead of normal kind dispatch.
Hook run when a queue item transitions to done status. Each function is called with two arguments: BUF-NAME and ITEM.
Open (or refresh) the agent-shell-queue buffer.
Switch to the agent-shell-queue buffer in the current window.
Narrow the queue buffer view: choose global, a directory, or a specific buffer.
Reset the queue buffer to the global scope (show all items).
Keymap for agent-shell-queue-mode.
Major mode for reviewing and managing the agent-shell prompt queue.
In addition to any hooks its parent mode tabulated-list-mode might have run, this mode runs the hook agent-shell-queue-mode-hook, as the final or penultimate step during initialization.
Key Binding
C-a agent-shell-queue-buffer-archive C-e agent-shell-queue-edit-task TAB agent-shell-queue-buffer-jump-to-next C-k agent-shell-queue-buffer-remove RET agent-shell-queue-buffer-view-item C-v agent-shell-queue-select-columns C-w agent-shell-queue-insert-wait SPC agent-shell-queue-buffer-context-menu = agent-shell-queue-buffer-inspect-item ? describe-bindings B agent-shell-queue-buffer-disable-background-task D agent-shell-queue-show-disk-state M agent-shell-menu-dispatch a agent-shell-queue-buffer-capture-after b agent-shell-queue-buffer-enable-background-task c agent-shell-queue-capture e agent-shell-queue-enqueue-dispatch g agent-shell-queue-buffer-refresh i agent-shell-queue-interject m agent-shell-queue-dispatch n agent-shell-queue-set-scope o agent-shell-queue-buffer-open-shell p agent-shell-queue-buffer-pause q quit-window r agent-shell-queue-buffer-schedule u agent-shell-queue-capture-unassigned w agent-shell-queue-scope-global y agent-shell-queue-capture-from-clipboard z agent-shell-queue-buffer-mark-done C-DEL agent-shell-queue-buffer-remove M-<down> agent-shell-queue-buffer-move-down M-<up> agent-shell-queue-buffer-move-up <down> agent-shell-queue-next-item <up> agent-shell-queue-prev-item
M-r agent-shell-queue-reload
C-d C-c agent-shell-queue-insert-clear-context C-d a agent-shell-queue-buffer-abort C-d c agent-shell-queue-insert-compact C-d i agent-shell-queue-import C-d p agent-shell-queue-insert-pause C-d x agent-shell-queue-raw-edit
C-c C-p agent-shell-queue-session-pause C-c C-r agent-shell-queue-session-resume C-c C-s agent-shell-queue-buffer-send C-c C-x agent-shell-queue-recover-stuck-shell C-c j #<hud-robot-agent-shell-map 173>
Rebuild the tabulated list from current queue state.
Move point to the first line of the next queue item.
Move point to the first line of the previous queue item.
Move point to the next item that will be dispatched.
Pause the item at point — suspend it from auto-dispatch without removing it.
Schedule the paused item at point — resume it for auto-dispatch. For blocked.task items, cascades active to subsequent blocked.dep items. Draft items are promoted directly to active without cascade.
Unblock the item at point (blocked.task → active with cascade).
Unblock the displayed item.
Remove the item at point from the queue, with confirmation.
Send the item at point to its target buffer now. When another task is already running for the same session, behavior adapts based on the item’s current status — see agent-shell-queue--send-now.
Remove the running item ID from queue tracking without interrupting it. The underlying shell process continues; only queue bookkeeping is dropped. Unlike agent-shell-queue-buffer-abort, no interrupt signal is sent and the session queue is not paused.
Remove the running item at point from queue tracking without aborting it.
Remove the displayed running item from queue tracking without aborting it.
Append an active copy of the running item ID to the end of its queue. The current run continues unaffected; the copy will dispatch when it finishes.
Append a copy of the running item at point to the end of its queue.
Append a copy of the displayed running item to the end of its queue.
Create a new active queue item from the done item with ID. The new item’s ‘reenqueued-from’ field is set to ID; ID’s ‘reenqueued-as’ list is updated with the new item’s ID. The original item’s ‘response’ field is not modified. When the original target buffer is dead, prompts for a live replacement.
Re-enqueue the done or aborted item at point as a new active item.
Show the Buffer column in the queue buffer. Toggle 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.
Toggle visibility of the Buffer column in the queue buffer.
Toggle visibility of the ordinal (#) column in the queue buffer.
Toggle visibility of the Age column in the queue buffer.
Toggle visibility of the Kind column in the queue buffer.
Toggle multi-line display format for the queue buffer.
Pick column display options via annotated-completing-read. Offers bulk presets, per-column visibility toggles, and multi-line switch. Changes take effect immediately via agent-shell-queue-buffer-refresh.
Keymap for agent-shell-queue-item-view-mode.
Read-only view of a single agent-shell queue item.
In addition to any hooks its parent mode markdown-mode might have run, this mode runs the hook agent-shell-queue-item-view-mode-hook, as the final or penultimate step during initialization.
Key Binding
C-a agent-shell-queue-item-view-archive C-d agent-shell-queue-item-destructive-menu C-k agent-shell-queue-item-view-remove C-t agent-shell-queue-item-view-reassign-all-detached B agent-shell-queue-item-view-disable-background-task E agent-shell-queue-item-view-enqueue-running-copy R agent-shell-queue-item-view-reenqueue T agent-shell-queue-item-view-reassign-detached U agent-shell-queue-item-view-untrack-running X agent-shell-queue-item-view-abort a agent-shell-queue-item-view-actions b agent-shell-queue-item-view-enable-background-task d agent-shell-queue-item-view-pause e agent-shell-queue-item-view-edit f agent-shell-queue-item-view-unblock g agent-shell-queue-item-view-refresh i agent-shell-queue-item-view-inspect m agent-shell-queue-item-menu o agent-shell-queue-item-view-open-shell q quit-window s agent-shell-queue-item-view-send t agent-shell-queue-item-view-assign u agent-shell-queue-item-view-schedule z agent-shell-queue-item-view-mark-done C-DEL agent-shell-queue-item-view-remove M-<down> agent-shell-queue-item-view-move-down M-<up> agent-shell-queue-item-view-move-up
Open an item-view window below showing the item at point.
Interactively pick any queue item and display it in the item-view buffer.
Refresh the content of the current item-view buffer.
Send the displayed item to its target buffer now. When another task is already running for the same session, behavior adapts based on the item’s current status — see agent-shell-queue--send-now.
Remove the displayed item from the queue, with confirmation.
Pause the displayed item — suspend it from auto-dispatch.
Schedule the displayed item — resume it for auto-dispatch.
Re-enqueue the displayed done or aborted item as a new active item.
Archive the displayed item and close the view. Archiving must be enabled via agent-shell-queue-archive-enabled.
Flag the displayed item for background sub-agent execution.
Clear the background sub-agent flag from the displayed item.
Move the displayed item one position earlier in its queue.
Move the displayed item one position later in its queue.
Assign the displayed item to a different agent-shell buffer.
Assign this detached item to an active or newly created shell.
Assign all items in the same dead bucket to an active or new shell.
Assign all detached items across all buckets to an active or new shell.
Open the edit buffer for the displayed item.
Keymap for agent-shell-queue-inspect-mode.
Minor mode active in queue item inspect buffers.
Binds p/j/y to switch formats, g to refresh, q to quit.
This is a minor mode. If called interactively, toggle the ‘Agent-Shell-Queue-Inspect 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-inspect-mode.
The mode’s hook is called both when the mode is enabled and when it is disabled.
Key Binding
g agent-shell-queue-inspect-refresh j agent-shell-queue-inspect-as-json p agent-shell-queue-inspect-as-plist q quit-window y agent-shell-queue-inspect-as-yaml
Refresh the current inspect buffer from live queue state.
Show the current inspect item as a plist.
Show the current inspect item as JSON.
Show the current inspect item as YAML.
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).
Interrupt the running item at point and mark it as aborted. Pauses the session queue — call agent-shell-queue-session-resume to restart.
Interrupt the running displayed item and mark it as aborted. Pauses the session queue — call agent-shell-queue-session-resume to restart.
Destructive actions for the item shown in the current item-view buffer.
Show available item-view actions via annotated-completing-read.
Move the item at point one position earlier.
Move the item at point one position later.
Flag the item at point for background sub-agent execution.
Clear the background sub-agent flag from the item at point.
Assign the item at point to a compatible buffer or unassigned. Candidate buffers are filtered by the item’s kind via the type registry. Offers nil/unassigned as an option for deferred assignment.
Offer context-sensitive actions for the item at point via completing-read.
Toggle queue-only mode in the shell buffer for the item at point. Done and aborted items cannot be attached to a shell — re-enqueue them first. When the shell buffer is dead, picks a live replacement via completing-read.
Return non-nil when queue-intercept mode is active in the current shell buffer.
Return agent-shell-queue-input-mode for current shell buffer or default.
Enable queue-only input mode in current shell buffer.
Return non-nil when queue-only mode is active in the current shell buffer.
Disable queue-only input mode in BUF (defaults to current buffer).
Disable queue-only input mode in current shell buffer.
Disable queue-only input mode across all agent-shell buffers.
Switch to the shell buffer for the item at point. If the buffer is not live and the item’s executor provides a create function, offer to create a new buffer of the same type.
Switch to the shell buffer for the item shown in this view. If the buffer is not live and the item’s executor provides a create function, offer to create a new buffer of the same type.
This function has :before advice: agent-shell-queue-destructive-menu@guard-queue-buffer.
(fn)
This function has :before advice: agent-shell-queue-destructive-menu@guard-queue-buffer.
(fn)
This function has :before advice: agent-shell-queue-dispatch@guard-queue-buffer.
(fn)
This function has :before advice: agent-shell-queue-dispatch@guard-queue-buffer.
(fn)
Choose kind and target buffer via ACR, then collect input. Choices are built from the item-type registry. nil/unassigned is always offered as a target so items can be deferred for later assignment.
Export items in the current scope to a read-only YAML buffer. Multi-line prompt/response fields are formatted as literal block scalars.
Keymap for agent-shell-queue-edit-mode.
Mode for editing a queued prompt in a popup buffer.
In addition to any hooks its parent mode markdown-mode might have run, this mode runs the hook agent-shell-queue-edit-mode-hook, as the final or penultimate step during initialization.
Key Binding
C-x C-s agent-shell-queue-edit-save-and-flush
C-c C-c agent-shell-queue-edit-confirm C-c C-f agent-shell-queue-insert-file C-c C-k agent-shell-queue-edit-cancel
C-c M-f agent-shell-queue-insert-buffer
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.
Save the edited prompt, close the popup, and flush the queue to disk.
Save the edited prompt and close the popup.
Discard edits and close the popup.
Keymap for agent-shell-queue-raw-edit-mode.
Mode for directly editing the queue in YAML format. Every session not already paused is paused while this buffer is live. Confirm with M-x agent-shell-queue-raw-edit-confirm, cancel with M-x agent-shell-queue-raw-edit-cancel.
Key Binding
C-c C-c agent-shell-queue-raw-edit-confirm C-c C-k agent-shell-queue-raw-edit-cancel
In addition to any hooks its parent mode text-mode might have run, this mode runs the hook agent-shell-queue-raw-edit-mode-hook, as the final or penultimate step during initialization.
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.
Validate and apply the YAML in this raw-edit buffer.
Cancel raw edit; resume exactly the sessions this raw edit newly paused.
Import queue items from SOURCE (YAML). With no prefix arg reads from clipboard; with prefix arg prompts for file. For items whose ID exists, prompts to keep, replace, or assign new ID.
no docstring
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.
Execute BODY with BUF’s queue session paused, then always resume it. BUF can be a buffer object or buffer name string. Directly manipulates the session-paused list to avoid spurious messages during setup. Always resumes and saves even if BODY signals an error.
Fork the queue for SOURCE-BUF starting at FROM-ID into a new session.
Items at or after FROM-ID (by queue position among active/deferred/draft) 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’. :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.
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).
Insert a pause item into BUF’s queue, optionally at 1-based POSITION. If DURATION is specified (seconds), pause auto-resumes after DURATION. When called interactively, prompts for target buffer (and duration with prefix arg).
Set pre-dispatch DELAY (in seconds) for queue item ID.
Set post-completion DELAY (in seconds) for queue item ID.
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.
Insert a compact (non-LLM manual) item with PROMPT into BUF’s queue. When dispatched the item pauses the queue and alerts; use agent-shell-queue-mark-done to complete it and advance the queue.
Mark item ID as done without dispatching it through the LLM. If the item is a compact item that paused a session, the session is resumed and the queue advances to the next item.
Mark the item at point as done.
Mark the displayed item as done.
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.
Capture mode for interjection messages. Confirm with M-x agent-shell-queue-interjection-send, close with M-x agent-shell-queue-interjection-close.
In addition to any hooks its parent mode text-mode might have run, this mode runs the hook agent-shell-queue-interjection-mode-hook, as the final or penultimate step during initialization.
Send the interjection message to the agent shell and close this buffer.
Close interjection buffer with choice of handling interrupted task.
Return non-nil when agent-shell-queue-interject can be called. True when queue data is loaded, a task is running or interjecting, and no interjection buffer is already pending.
Interrupt the currently running queue task and open an interjection buffer.
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.
no docstring
Set input MODE for BUF (default: current buffer). MODE must be one of default, ‘queue-intercept’, or ‘queue-only’. Enforces mutual exclusivity and updates the prompt indicator.
Cycle input mode: default → queue-intercept → queue-only → default.
Toggle queue-intercept mode for BUF; when active, user-typed input is queued.
Enable queue-intercept mode in BUF so user-typed input is queued.
Disable queue-intercept mode in BUF, returning it to default input mode.
Reset all live agent-shell buffers in queue-intercept mode to default.
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 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.
no docstring
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.
no docstring
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
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 between tasks. 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 ‘org’ — Org-mode file backend via ‘agent-shell-queue-org’
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.
Alist mapping ‘<agent-shell-identifier>‘ to background prefix string.
Alist mapping ‘<agent-shell-identifier>‘ to clear command string.
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. Controls whether agent-shell-queue-buffer-archive is active. The destination path is controlled separately by agent-shell-queue-archive-file-function.
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 safe-save is non-nil. Nil means use a subdirectory of variable temporary-file-directory named “emacs-<instance>” where <instance> comes from agent-shell-queue-instance-name.
Serialization format for safe-save backups. When nil, 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.
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.
Create the done_items table and register a hook to record completed items. This supplements (does not replace) agent-shell-queue-done-log-file. Call after agent-shell-queue-db-enable.
Maximum entries retained in agent-shell-queue--write-log.
When non-nil, log persistence events to agent-shell-queue-log buffer.
Display the in-memory write log in a readable buffer.
(fn FORMAT)
Return the file extension string (with leading dot) for FORMAT.
(fn FORMAT)
Return the file extension string (with leading dot) for FORMAT.
(fn FORMAT)
Return the file extension string (with leading dot) for FORMAT.
(fn FORMAT)
Return the file extension string (with leading dot) for FORMAT.
Register serialization FORMAT with SERIALIZE-FN and DESERIALIZE-FN. FMT is a symbol; SERIALIZE-FN takes one argument (an items alist) and returns a string; DESERIALIZE-FN takes a string and returns an items alist. Installs cl-generic methods for agent-shell-queue--serialize-items and agent-shell-queue--deserialize-items specialised on (eql FMT).
Serialize STORE to a string using the format recorded in STORE.
Parse STRING using the format in STORE, returning an items alist.
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.
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.
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.
(fn FORMAT)
Return the file extension string (with leading dot) for FORMAT.
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.
Hash table of symbol id to ‘agent-shell-prompt-spec’. Populate via register-agent-shell-prompt.
Return the ‘agent-shell-prompt-spec’ registered under ID, or nil.
Return all registered ‘agent-shell-prompt-spec’ values.
(fn &key ID DOC CATEGORY ARGS PRE-OP TEMPLATE SUBMIT TARGET POST-OP)
Register a prompt spec built from ID, DOC, CATEGORY, ARGS, PRE-OP. TEMPLATE, SUBMIT, TARGET, and POST-OP. Re-registering an existing ID replaces the entry.
Define and register a prompt workflow named ID. KEYS is a plist accepting the same keys as agent-shell-prompt-register (:doc :category :args :pre-op :template :submit :target :post-op). :args is data (an arg-spec list), not code, and is quoted automatically.
Render TEMPLATE, substituting {{key}} placeholders from CTX. CTX is a plist; {{args.KEY}} looks inside the :args sub-plist, any other {{key}} looks up the top-level :key entry.
Run SPEC’s pre-op against CTX, then call CALLBACK with the updated ctx. When SPEC has no pre-op, CALLBACK is invoked with CTX unchanged. A pre-op of arity 1 is treated as synchronous and must return the updated ctx; a pre-op of arity 2 is treated as asynchronous and must itself call its callback argument with the updated ctx.
Run SPEC’s post-op with SHELL-BUFFER, CTX, and RESPONSE-TEXT. Returns the post-op’s control-flag result, or :done when SPEC has no post-op. See ‘agent-shell-prompt-spec’ for the set of recognized flags.
(fn ID &key ARGS TARGET (SUBMIT nil SUBMIT-SUPPLIED-P))
Run the prompt workflow registered as ID. ARGS is a plist of pre-known argument values; any argument the spec declares but ARGS omits is collected interactively. TARGET and SUBMIT override the spec’s defaults when supplied.
Pick a registered prompt via annotated-completing-read and dispatch it. Candidates are annotated with their category and one-line doc. With CATEGORY non-nil, only prompts in that category are offered.
Single entry point into the agent-shell-prompt ACR picker.