Agent status viewer
A small Electron window that shows the live status of the agent sessions on
this machine, from the session-status board.
It shows one card per session: state, project, task, blocker, items left,
ETA and projected tokens (self-reported in
~/.agent-behaviors/status/<session>.json), joined with measured token
usage from usage.py. Sessions with
usage but no board entry appear as unreported. The header pills show
whether each <model>.status background session is alive.
Each card links to the session's context folder (where its agent keeps the
session) and its memory; when one is gone or unknown, the card says so.
Message… on a card sends a prompt to that agent, whatever it is
(Copilot, Claude, Codex, Gemini, Mistral, Grok, …): it lands in the
session's inbox (~/.agent-behaviors/status/inbox/<session>/), and the agent
reads it the next time it publishes its status. The card shows messages
still waiting and when the last one was read. Open session takes you to
the agent instead, to type to it directly. For a Claude Code session it opens
a chat window: your messages continue that session (claude -p --resume
with streaming JSON), with / for its slash commands, @ to add a file of
the project as context, Attach… for documents and images, Stop, and a
Permissions menu (ask denies tools that need approval; pick acceptEdits,
plan, … to allow more). If the session is still live elsewhere, the first
message forks it into a new session, so the two never write one
conversation. Other agents: Terminal with claude attach for a background
Claude Code session, otherwise the project folder.
A live session that doesn't report (active in the last 15 minutes, or
running per claude agents) also gets Onboard: it copies a
prompt asking the agent to load the session-status skill and publish under
its own session id, and opens the session so you can paste it there (an
unreported agent doesn't read the inbox).
The board refreshes as soon as a file changes. How often it also polls the
board and re-measures usage is set in ~/.agent-behaviors/session-status.json
(viewerBoardSeconds, viewerUsageSeconds); a valid edit applies at once.
The Settings button in the header edits that file in place while the
viewer runs: values are checked against their ranges, and they apply as
soon as they are saved.
The viewer only reads: it never writes a session entry. Its own usage.py
deltas are kept in .usage-viewer.json, apart from everyone else's.
At start, the app deploys this repository's skills into the AgentsMonitor
folder (AGENTS_MONITOR_FOLDER, default ~/.agent-behaviors), as the VS Code
extension does: skills/ with a generated skills/README.md that agents read
to register the skills, and a technical README.md at the folder's root
(docs/architecture.md). It then offers to add the
skills to every agent installed on this machine that lacks them (Claude
Code, GitHub Copilot, Codex, Gemini CLI, Mistral Vibe, ~/.agents): each
skill is linked into the agent's skills folder, and nothing already there is
replaced. Don't ask again is remembered.
The same view is available inside VS Code: see vscode/.
Both share the status monitor, renderer and styles in shared/.
Every tool a skill relies on must be allowed for the agents: an agent has to
be able to run it without being blocked or asked each time, or the skill
can't do its job. Today that means:
When a skill is added or starts using a new tool, list the tool in the
skill's tools.json and in this table, then run
setup/allow-tools.py: it allows every listed tool
in each agent it detects (Claude Code, Copilot in VS Code, Codex) and says
what to allow by hand in the others. The Tools section
of the main README says how to install them.
Tests
cd viewer
npm install
npm test # or: cd vscode && npm test
