{"id":50897036,"url":"https://github.com/yrstm/agentdash","last_synced_at":"2026-06-16T01:01:59.245Z","repository":{"id":364121537,"uuid":"1265717120","full_name":"yrstm/agentdash","owner":"yrstm","description":"w for your AI agents - a terminal table of every coding agent on a box and whether it needs your input","archived":false,"fork":false,"pushed_at":"2026-06-11T18:26:33.000Z","size":483,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T19:16:42.042Z","etag":null,"topics":["ai-agent","bash","claude-code","cli","monitoring","tmux","tui"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yrstm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T02:52:51.000Z","updated_at":"2026-06-11T14:29:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yrstm/agentdash","commit_stats":null,"previous_names":["yrstm/agentdash"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yrstm/agentdash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yrstm","download_url":"https://codeload.github.com/yrstm/agentdash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34386320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","bash","claude-code","cli","monitoring","tmux","tui"],"created_at":"2026-06-16T01:01:32.905Z","updated_at":"2026-06-16T01:01:59.227Z","avatar_url":"https://github.com/yrstm.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agentdash\n\n`w`, but for AI coding agents. agentdash prints a table of the agent\nprocesses on a Linux box: what each one is working on, what model it is\non, how full its context is, and whether it is blocked waiting on you.\n`-w` turns the table into a small interactive TUI.\n\nIt is a single static binary with zero runtime dependencies, reading\nthe session files agent CLIs already write locally (Claude Code and\nCodex are supported; adding another agent is a small parser, see\nCONTRIBUTING.md) and /proc directly. No daemon, no server, no API\ncalls, no telemetry, and it never launches or manages sessions. Watch\nmode is event-driven: a session write reaches the screen in\nmilliseconds, not at the next poll. I wrote it because I kept losing\ntrack of agents across tmux sessions; maybe it is useful to you too.\nLinux only.\n\n![demo](demo.gif)\n\n## Install\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/yrstm/agentdash/main/install.sh | sh\n```\n\nor grab the binary directly:\n\n```sh\ncurl -fsSLo ~/.local/bin/agentdash https://github.com/yrstm/agentdash/releases/latest/download/agentdash-linux-amd64\nchmod +x ~/.local/bin/agentdash\n```\n\nor with Homebrew (this also works on Linux), or go install:\n\n```sh\nbrew install yrstm/agentdash/agentdash\ngo install github.com/yrstm/agentdash/cmd/agentdash@latest\n```\n\nIt is a single static binary with zero runtime dependencies. Optional:\ntmux (pane jumping, attachment glyphs), docker (sandbox section, skipped\nif absent), jq (only for the integrations). The auditable v1 bash\nversion lives in `legacy/` and keeps working.\n\n## Usage\n\n```\nagentdash              print the table once\nagentdash -w [secs]    watch mode (default 5s), keys below\nagentdash -a           expand collapsed rows and healthy sections\nagentdash -l           long view: adds PID, TTY, UP columns\nagentdash -t           tree view: group agents under the wrapper that spawned them\nagentdash --json       machine-readable output (schema_version 1)\nagentdash --plain      no color, no glyphs; NO_COLOR is honored\nagentdash --any-waiting   exit 0 if anything needs you\n\nagentdash go [row|pid]     jump to that agent's tmux pane\nagentdash show \u003crow|pid\u003e   drill-down with recent turns and resume command\nagentdash why \u003crow|pid\u003e    where every value on the row came from\nagentdash label \u003crow|pid\u003e \"text\"   pin a task label\nagentdash resume \u003crow|pid\u003e print the resume command for a session\nagentdash recap [4h]       what changed since you last looked\n```\n\n### Watch mode keys\n\nWatch mode has a cursor (`▸`); keys act on the selected row. Panels open\nover the board and any key returns to it.\n\n```\nj/k or arrows   move the cursor\ng               jump to the agent's tmux pane\ns               drill-down panel: recent turns, session path, resume command\ny               provenance panel: where each value on the row came from\nL               edit the task label\nr               show the resume command\n/               filter rows across task, cwd, model, status (Esc clears)\no               cycle sort: urgency, last-write, tokens, uptime\nt               toggle tree view        l   toggle long view\na               toggle expanded view    ?   help\nmouse           wheel scrolls, click selects (off under --plain)\nq               quit\n```\n\nThe board refreshes when a session file changes (fsnotify, debounced),\nnot on a timer; process starts and exits are picked up by a cheap /proc\nscan every second (`AGENTDASH_PROC_TICK`).\n\n## The table\n\n```\ndevbox 14:02 · 2 need you · 3 working · 6 idle · 8m ctx held idle · load 0.27\n\n  AGENT    LAST  MODEL      TOKENS     CTX        ACT      STATUS     CWD        TASK\n▸ claude ○ 4m    opus-4-8   34m/359k   ▓▓▓░░  45%   ▅▂▁    waiting    ~/c/api    settlement reconciliation\n  claude ● 12s   fable-5    18m/285k   ▓▓░░░  35%   ▆█▇▅   working    ~          migrate the queue\n  + 2 wrappers · 1 unmatched (-a to list)\n\n  ok: tmux ×4 · logins ×2 · sandboxes ×3 · ports ×4 · no zombies\n```\n\nRows sort by urgency and keep their order between refreshes. Healthy\nsections collapse into the `ok:` line and expand only when something is\nflagged; pass `-a` (or set `AGENTDASH_EXPAND=1`) to always expand\neverything. Defunct (zombie) processes and orphaned wrapper processes — a\n`bash -c`/`nohup` launcher still running with no controlling tty after its\nagent has exited — surface in a ZOMBIES \u0026 ORPHANS section when present.\nGlyphs: `●` tmux attached, `○` detached; a red `○` means the agent is\nwaiting and nobody is attached.\n\nColumns: LAST is time since the session file was written. TOKENS is\ncumulative input/output, where input includes cache reads and writes (it\nmeasures context fill, not billing). CTX is the last request against the\nmodel's context window, yellow at 70%, red at 85%. ACT is bytes appended\nper refresh over the last 8 intervals. TASK is your label, else the\nsession's summary, else the first prompt; a trailing `?` means the\nprocess-to-session pairing was heuristic.\n\nColors carry one meaning each: green working, yellow worth a look, red\nneeds you now, dim ignorable. A healthy board is almost colorless.\n\nTree view (`-t`, or `t` in watch mode) regroups the rows so an agent sits\nunder the wrapper process that spawned it, found by walking the ppid\nchain. Urgency order still applies to the top level.\n\n## Design notes\n\nagentdash started life as a bash script with an embedded stdlib-only\nPython parser: session files are JSONL with nested, escaped content\n(prompts hold quotes, unicode, pasted code), which bash regex cannot\nparse correctly, and jq would have been a lateral dependency swap that\nloses the stateful incremental scan. v1 proved the heuristics in\nbash+python; v2 compiles them. The genre's reference tools (`w`,\n`htop`) are compiled C for a reason: the Go version reads /proc and\nthe session files directly, drops the procps/iproute2/python3\ndependencies entirely, and turns the polling watch loop into an\nfsnotify subscription. The v1 script is preserved, working, in\n`legacy/agentdash.sh`; `tools/parity.sh` holds the two implementations\nto identical `--json` output. The only socket the tool will ever open\nis the local docker unix socket for the sandboxes section, and CI\nenforces that with strace.\n\nThe scanner is incremental by byte offset: each render stats every\npaired session file and parses only the bytes appended since the last\nlook, folding them into a cached per-session entry. Only complete lines\nare consumed, since an agent may be mid-write; a partial tail line\nwaits for the next refresh. That is why a board over gigabytes of\nsession history costs milliseconds once the cache is warm.\n\nPairing a pid to a session file never guesses silently. A five-tier\nevidence chain runs from exact to heuristic, records which tier fired,\nand anything below the confident tiers is marked with a `?` on the\nboard. `agentdash why \u003crow\u003e` prints the recorded evidence for every\nvalue on the row.\n\n## Performance\n\nMeasured with the reproducible suite in `bench/` (4-core container,\n25 MB session corpus, methodology and caveats in\n[docs/benchmarks/](docs/benchmarks/v2-comparison.md)):\n\n| metric | v1 (bash+python) | v2 (Go) |\n|---|---|---|\n| one-shot render, warm cache | 174 ms | 15 ms |\n| one-shot render, cold cache (25 MB) | 562 ms | 368 ms |\n| idle watch CPU, 10 min avg | 3.65 % | 0.29 % |\n| session write to screen | ~2.3 s | ~80 ms |\n| peak memory (PSS), cold render | 38 MB | 17 MB |\n| dependencies on a clean box | bash python3 procps iproute2 | none |\n\n## How values are derived\n\nPairing a process to a session file walks an evidence chain: an open fd\nin /proc, then a unique session file in the project dir for the process\ncwd, then a first-entry timestamp within 5 minutes of process start,\nthen a sticky previous guess, then the newest unclaimed recent file\n(the last two are heuristic and marked `?`). Codex sessions record\ntheir cwd and start time in the rollout file, which pairs them\ndirectly. `agentdash why \u003crow\u003e` prints which tier applied.\n\nStatus: file written under 60s ago is `working`; over 10 minutes quiet is\n`idle`; in between, `waiting` if the last entry is an assistant turn, else\nit is graded by how long it has been quiet on a user/tool entry: `busy?`\n(dim) under `AGENTDASH_STUCK_SECS` (default 90s) — likely a slow tool call,\nnot alarming — and `stuck?` (red) past it. This grading replaces the old\nflat \"silent over a minute = stuck?\" false positive. `respawn ×N` means\nthree or more fresh pids on one session file within 10 minutes. Thresholds\nare configurable via `AGENTDASH_WORKING_SECS`, `AGENTDASH_STUCK_SECS` and\n`AGENTDASH_IDLE_SECS`.\n\nContext windows come from `~/.config/agentdash/context-windows.conf`\n(`\u003cmodel-id-substring\u003e \u003cwindow-tokens\u003e`, first match wins), then built-in\ndefaults, then self-correction: if observed context exceeds the assumed\nwindow, the larger tier is adopted and written back to the conf.\n\nPort flags: `NEW` is first seen since the previous run, `dup-cwd` is two\nlisteners in one project directory, `no-agent` is a tty-less listener in a\nproject directory no agent or tmux pane is using.\n\n## Privacy\n\nThe TASK column shows prompt text and the cache at\n`~/.cache/agentdash/usage.json` persists it (mode 0600). Mind\nscreen-sharing and log shipping.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyrstm%2Fagentdash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyrstm%2Fagentdash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyrstm%2Fagentdash/lists"}