{"id":50928555,"url":"https://github.com/yrstm/agentdash1","last_synced_at":"2026-06-17T02:00:56.846Z","repository":{"id":364121537,"uuid":"1265717120","full_name":"yrstm/agentdash1","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-16T21:42:56.000Z","size":1368,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T23:21:48.020Z","etag":null,"topics":["ai-agent","bash","claude-code","cli","monitoring","tmux","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","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-16T21:44:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yrstm/agentdash1","commit_stats":null,"previous_names":["yrstm/agentdash","yrstm/agentdash1"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/yrstm/agentdash1","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash1","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash1/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash1/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash1/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yrstm","download_url":"https://codeload.github.com/yrstm/agentdash1/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yrstm%2Fagentdash1/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34430688,"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-17T02:00:05.408Z","response_time":127,"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-17T02:00:24.034Z","updated_at":"2026-06-17T02:00:56.807Z","avatar_url":"https://github.com/yrstm.png","language":"Go","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, no file watcher, and it never launches or manages\nsessions. Watch mode samples foreground state on the TUI refresh tick,\nlike `w` or `htop`. I wrote it because I kept losing track of agents\nacross tmux sessions; maybe it is useful to you too. Linux 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\ntab             switch between Agents and History\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\nHistory view: s details, r resume, i read/command disclosure\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 on foreground TUI ticks. Process starts and exits\nare picked up by a cheap /proc scan every second (`AGENTDASH_PROC_TICK`);\nthe full board and History view resample on the watch interval.\n\n## Event hooks\n\nWatch mode can run a command of yours when an agent changes state, so you\ncan fire-and-forget an agent and be reached only when it actually needs\nyou — a desktop toast, a phone push, a Slack message, a log line:\n\n```\nagentdash -w --on-needs-you \u003ccmd\u003e   run \u003ccmd\u003e when an agent enters a needs-you state\nagentdash -w --on-stuck \u003ccmd\u003e       run \u003ccmd\u003e when an agent's status becomes stuck?\n```\n\nThe command runs through `sh -c`, so quote it as one argument. It fires\nonce on the *transition into* the state (not repeatedly while it lasts),\nand only with `-w`. agentdash itself opens no socket and makes no network\ncall; your command is what reaches out.\n\nEach invocation receives the agent as JSON on **stdin** — one object,\nbyte-identical to an entry in the `agents` array of `agentdash --json`,\nwrapped in an envelope:\n\n```json\n{\"event\":\"needs_you\",\"ts\":1718566400,\"attached\":false,\"agent\":{\"agent\":\"claude\",\"pid\":4123,\"needs_you\":true,\"status\":\"waiting\",\"cwd\":\"/home/yas/code/incred-be\",\"task\":\"reconcile merge\",…}}\n```\n\n`attached` is whether someone is on its tmux pane (so a notifier can stay\nquiet for agents you are already watching). For quick shell one-liners the\nheadline fields are also in the environment: `AGENTDASH_EVENT`,\n`AGENTDASH_PID`, `AGENTDASH_TASK`. A `stuck?` transition counts as\nneeds-you too, so with both hooks set it fires both events; deduplicate on\n`event` if that matters. Commands run non-blocking and are bounded by a\n10s timeout, so a slow or wedged hook never stalls the board.\n\nA minimal example notifier lives in `integrations/notify-example.sh`:\n\n```sh\nagentdash -w --on-needs-you 'integrations/notify-example.sh'\n```\n\nTo let another agent read and triage the fleet through the same CLI (no\nMCP needed), see [docs/agent-interface.md](docs/agent-interface.md).\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    flaky checkout test\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 keeps watch mode as a foreground sampler\nwith no daemon, listener, or file watcher. 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%2Fagentdash1","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyrstm%2Fagentdash1","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyrstm%2Fagentdash1/lists"}