Skip to content

About

Mode-line attention tracker for agent-shell

Resources

Stars

16 stars

Watchers

1 watching

Forks

Latest commit

 

History

50 Commits

Folders and files

Repository files navigation

agent-shell-attention: Mode-line attention tracker for agent-shell

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.

Installation

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.

Usage

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 live agent-shell buffers, sorted by status (awaiting, running, idle), with agent icons, session titles, last-active timestamps, and coloured status text (Idle, Awaiting, Running, or Permissions: (...)). You can also call M-x agent-shell-attention-dashboard directly. In the dashboard, RET visits the session, o visits in another window, j opens the session’s ambient directory, and D kills 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-buffer to 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.

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

Basic customization

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)

Notifications

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

Further customization

M-x customize-group RET agent-shell-attention RET.

  • The lighter text is controlled by agent-shell-attention-lighter (default: " AS:%d") or agent-shell-attention-render-active (default: " AS:%d/%d") according to whether agent-shell-attention-render-function is agent-shell-attention-render-pending or agent-shell-attention-render-active.
  • Choose where the indicator is installed with agent-shell-attention-indicator-location. Set it to mode-line-misc-info (default) to sit next to other minor-mode indicators, or to global-mode-string if 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, customize agent-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-icons is enabled.
  • If you want imenu-like group headings in C-u M-x agent-shell-attention-jump (some completion UIs support this), set agent-shell-attention-jump-show-groups to 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 with M-x tab-recent.

Workspace activation

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)

Example configuration

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

Integration

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.

About

Mode-line attention tracker for agent-shell

Resources

Stars

16 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages