agentdash

w, but for AI coding agents. agentdash prints a table of the agent processes on a Linux box: what each one is working on, what model it is on, how full its context is, and whether it is blocked waiting on you. -w turns the table into a small interactive TUI.

It works by reading the session files agent CLIs already write locally (Claude Code and Codex are supported; adding another agent is a small parser, see CONTRIBUTING.md). No daemon, no server, no API calls, and it never launches or manages sessions. I wrote it because I kept losing track of agents across tmux sessions; maybe it is useful to you too. Linux only, bash 4+.

Install

curl -o ~/bin/agentdash https://raw.githubusercontent.com/yrstm/agentdash/main/agentdash
chmod +x ~/bin/agentdash

or with Homebrew (this also works on Linux):

brew tap yrstm/agentdash https://github.com/yrstm/agentdash
brew install agentdash

It is a single bash script. Needs bash, python3, procps, iproute2. Optional: tmux (pane jumping, attachment glyphs), docker (sandbox section, skipped if absent), jq (only for the integrations).

Usage

agentdash              print the table once
agentdash -w [secs]    watch mode (default 5s), keys below
agentdash -a           expand collapsed rows and healthy sections
agentdash -l           long view: adds PID, TTY, UP columns
agentdash -t           tree view: group agents under the wrapper that spawned them
agentdash --json       machine-readable output (schema_version 1)
agentdash --plain      no color, no glyphs; NO_COLOR is honored
agentdash --any-waiting   exit 0 if anything needs you

agentdash go [row|pid]     jump to that agent's tmux pane
agentdash show <row|pid>   drill-down with recent turns and resume command
agentdash why <row|pid>    where every value on the row came from
agentdash label <row|pid> "text"   pin a task label
agentdash resume <row|pid> print the resume command for a session
agentdash recap [4h]       what changed since you last looked

Watch mode keys

Watch mode has a cursor (▸); keys act on the selected row. Panels open over the board and any key returns to it.

j/k or arrows   move the cursor
g               jump to the agent's tmux pane
s               drill-down panel: recent turns, session path, resume command
y               provenance panel: where each value on the row came from
L               edit the task label
r               show the resume command
t               toggle tree view        l   toggle long view
a               toggle expanded view    q   quit

The table

devbox 14:02 · 2 need you · 3 working · 6 idle · 8m ctx held idle · load 0.27

  AGENT    LAST  MODEL      TOKENS     CTX        ACT      STATUS     CWD        TASK
▸ claude ○ 4m    opus-4-8   34m/359k   ▓▓▓░░  45%   ▅▂▁    waiting    ~/c/api    settlement reconciliation
  claude ● 12s   fable-5    18m/285k   ▓▓░░░  35%   ▆█▇▅   working    ~          migrate the queue
  + 2 wrappers · 1 unmatched (-a to list)

  ok: tmux ×4 · logins ×2 · sandboxes ×3 · ports ×4 · no zombies

Rows sort by urgency and keep their order between refreshes. Healthy sections collapse into the ok: line and expand only when something is flagged. Glyphs: ● tmux attached, ○ detached; a red ○ means the agent is waiting and nobody is attached.

Columns: LAST is time since the session file was written. TOKENS is cumulative input/output, where input includes cache reads and writes (it measures context fill, not billing). CTX is the last request against the model's context window, yellow at 70%, red at 85%. ACT is bytes appended per refresh over the last 8 intervals. TASK is your label, else the session's summary, else the first prompt; a trailing ? means the process-to-session pairing was heuristic.

Colors carry one meaning each: green working, yellow worth a look, red needs you now, dim ignorable. A healthy board is almost colorless.

Tree view (-t, or t in watch mode) regroups the rows so an agent sits under the wrapper process that spawned it, found by walking the ppid chain. Urgency order still applies to the top level.

How values are derived

Pairing a process to a session file walks an evidence chain: an open fd in /proc, then a unique session file in the project dir for the process cwd, then a first-entry timestamp within 5 minutes of process start, then a sticky guess (marked ?). Codex sessions record their cwd and start time in the rollout file, which pairs them directly. agentdash why <row> prints which tier applied.

Status: file written under 60s ago is working; over 10 minutes quiet is idle; in between, waiting if the last entry is an assistant turn, stuck? if it is a user or tool entry (died mid-turn or a pending permission prompt). A tool call that is silent for over a minute reads as stuck?; that is a known false positive. respawn ×N means three or more fresh pids on one session file within 10 minutes. Thresholds are configurable via AGENTDASH_WORKING_SECS and AGENTDASH_IDLE_SECS.

Context windows come from ~/.config/agentdash/context-windows.conf (<model-id-substring> <window-tokens>, first match wins), then built-in defaults, then self-correction: if observed context exceeds the assumed window, the larger tier is adopted and written back to the conf.

Port flags: NEW is first seen since the previous run, dup-cwd is two listeners in one project directory, no-agent is a tty-less listener in a project directory no agent or tmux pane is using.

Privacy

The TASK column shows prompt text and the cache at ~/.cache/agentdash/usage.json persists it (mode 0600). Mind screen-sharing and log shipping.

License

MIT.