Small add-on for agent-shell that keeps track of which agent buffers are waiting for your input and shows a compact indicator in the mode line.
See NEWS for user-visible changes.
Install agent-shell-attention from this repository with your preferred
package manager, or place agent-shell-attention.el on your load-path and
require it. The example configuration below shows one Elpaca setup.
Enable the global minor mode:
(require 'agent-shell-attention)
(agent-shell-attention-mode 1)When one or more agent buffers need attention, an AS:n indicator appears in the mode line (pending buffers). Busy-but-not-pending work is not counted unless you opt in to the AS:n/m indicator (see below).
- Click the indicator to pick a pending agent buffer from a menu.
M-x agent-shell-attention-jump:- Without a prefix argument, jump to the oldest pending buffer.
- With
C-u, prompt with completion from all active agent-shell buffers (awaiting or busy) - With
C-u C-u, open a dashboard for all liveagent-shellbuffers, sorted by status (awaiting, running, idle), with agent icons, session titles, last-active timestamps, and coloured status text (Idle,Awaiting,Running, orPermissions: (...)). You can also callM-x agent-shell-attention-dashboarddirectly. In the dashboard,RETvisits the session,ovisits in another window,jopens the session’s ambient directory, andDkills the selected session.
M-x agent-shell-attention-jump-idle:- Without a prefix argument, return to the most recently visited idle shell.
Use
M-x bury-bufferto put it behind the other idle shells without closing it. - Visits through associated viewport buffers also count toward recency.
- With
C-u, choose an idle shell with completion, in the same order. - Shells awaiting replies or running requests are excluded.
- Without a prefix argument, return to the most recently visited idle shell.
Use
“Awaiting reply” prompts clear when you visit the buffer, while “tool permission” prompts remain pending until you respond to all outstanding permission prompts in that session.
The indicator renders a cached count snapshot, so redisplay does not scan buffers. State changes schedule a coalesced update after callbacks finish. While the mode is enabled, a one-second timer also reconciles the counts against subscribed agent buffers to catch requests made outside the command hooks. Requests detected this way may take up to one second to appear in the indicator. Navigation and dashboard commands query live state directly. Reconciliation also refreshes an open dashboard when buffer membership changes, even if the indicator counts stay the same. If a background update fails, the last successful counts remain visible and the failure is reported once until an update succeeds.
Bind the jump commands globally:
(keymap-global-set "C-z a" #'agent-shell-attention-jump)
(keymap-global-set "C-z b" #'agent-shell-attention-jump-idle)To display the number of pending and busy buffers as AS:n/m:
(setopt agent-shell-attention-render-function
#'agent-shell-attention-render-active)To show an indicator even when nothing is pending (for example, AS:0 or AS:0/0), set:
(setopt agent-shell-attention-show-zeros t)agent-shell-attention always echoes a short message when an agent finishes a turn or asks for permission.
To also show external notifications, set agent-shell-attention-notify-function, as follows.
Built-in desktop notifications (via notifications-notify):
(setopt agent-shell-attention-notify-function #'agent-shell-attention-notify-default)KnockKnock notifications (see knockknock):
(require 'knockknock)
(setopt agent-shell-attention-notify-function
(lambda (_buffer title body)
(knockknock-notify
:title title
:message body
:icon "nf-cod-bot"
:duration 5)))M-x customize-group RET agent-shell-attention RET.
- The lighter text is controlled by
agent-shell-attention-lighter(default:" AS:%d") oragent-shell-attention-render-active(default:" AS:%d/%d") according to whetheragent-shell-attention-render-functionisagent-shell-attention-render-pendingoragent-shell-attention-render-active. - Choose where the indicator is installed with
agent-shell-attention-indicator-location. Set it tomode-line-misc-info(default) to sit next to other minor-mode indicators, or toglobal-mode-stringif you prefer it near clock/battery status:
(setopt agent-shell-attention-indicator-location 'global-mode-string)If you want the indicator to show in the tab bar, make sure tab-bar-format includes tab-bar-format-global (the piece that mirrors global-mode-string up there). For instance:
(add-to-list 'tab-bar-format #'tab-bar-format-global t)Prefer to add only this indicator instead of the whole global-mode-string? Add the built-in helper agent-shell-attention-tab-bar-format:
(add-to-list 'tab-bar-format #'agent-shell-attention-tab-bar-format t)- If you want different window/tab display behavior for
agent-shell-attention-jump, customizeagent-shell-attention-display-buffer-action. - The prefix-argument jump pickers show aligned attention statuses and session titles, with agent icons when
agent-shell-show-config-iconsis enabled. - If you want imenu-like group headings in
C-u M-x agent-shell-attention-jump(some completion UIs support this), setagent-shell-attention-jump-show-groupsto non-nil. By default, the jump command will switch tabs if the agent buffer is already visible in another tab. After jumping, you can return to your previous tab withM-x tab-recent.
The agent-shell-attention-before-jump-hook runs before display and pending-state
clearing. Each function receives the live shell buffer, even when an existing
viewport will be shown. It also runs for dashboard visits, including o.
An error or quit in the hook leaves pending state unchanged.
For Doom’s workspaces module, this opt-in recipe activates the workspace owning the shell. If several workspaces contain it, the recipe asks which one to use. No workspace is created.
(defun my/agent-shell-attention-switch-workspace (buffer)
(when (bound-and-true-p persp-mode)
(let ((names
(mapcar #'safe-persp-name
(seq-filter
(lambda (workspace)
(+workspace-contains-buffer-p buffer workspace))
(+workspace-list)))))
(when names
(+workspace-switch
(if (cdr names)
(completing-read "Session workspace: " names nil t)
(car names)))))))
(add-hook 'agent-shell-attention-before-jump-hook
#'my/agent-shell-attention-switch-workspace)Here is a complete example config using elpaca:
(use-package agent-shell-attention
:ensure (:host github :repo "ultronozm/agent-shell-attention.el")
:after agent-shell
:demand
:bind (("C-z a" . agent-shell-attention-jump))
:config
(require 'knockknock)
(setopt agent-shell-attention-notify-function
(lambda (_buffer title body)
(knockknock-notify
:title title
:message body
:icon "nf-cod-bot"
:duration 5)))
(setopt agent-shell-attention-render-function
#'agent-shell-attention-render-active)
(setopt agent-shell-attention-indicator-location 'global-mode-string)
(agent-shell-attention-mode))Session browsers can use agent-shell-attention-unread-p to query unread
replies and agent-shell-attention-acknowledge to mark them as read.
Bind agent-shell-attention-inhibit-auto-acknowledge during previews,
then acknowledge the confirmed selection. Permission prompts remain pending.