A status bar chip that shows every running coding agent session at a glance: the Agent Watch robot, the number of agents working, and one dot per session. For now it supports Claude Code.
| Dot | Status | Meaning |
|---|---|---|
| 🟡 | Working | The agent is running a turn |
| 🔴 | Waiting | It needs your permission or an answer |
| 🟢 | Idle | It finished and is ready for more |
The number after the robot counts the agents working right now, like the Source Control count of changes; the panel's badge in the activity bar shows the same number. The robot takes the color of the most urgent status: red if any session is waiting, yellow if any is working. With no sessions, the chip says No agents, in the language VS Code uses (English and Spanish so far). Right after it, two rings show how much of your Claude plan's usage limits is used.
Agent Watch is not tied to a single agent, but for now it supports only Claude Code.
| Agent | Support | Needs |
|---|---|---|
| Claude Code | Supported (tested with 2.1.286) | The Claude Code extension for VS Code, or the claude CLI in a VS Code terminal |
Sessions open in the Claude Code extension's chat; CLI sessions focus their terminal instead. It works best on Linux; see Limitations.
This is a community project, not affiliated with or endorsed by Anthropic.
- Hover the chip to see the sessions in the same order as the dots, numbered, each with its title, status, time in that status, folder and branch, and what it is doing right now. Click a title to open that session. The filter links at the top (All · Working · Waiting · Idle) choose which sessions the chip and the panel show.
- Click the chip to open a searchable session picker. The first waiting session is highlighted, or else the one that just finished, so Enter takes you to it. The funnel button in its title bar opens the status filter.
- A funnel appears in the chip while a filter is active. The filter is remembered across restarts.
Right after the chip, two rings show how much of your Claude plan's usage limits is used, the ones Claude Code's /usage shows: the pastel blue one for the 5-hour session limit and the peach one for the weekly limit. Each has the percent written inside and, like a progress spinner, fills up clockwise as you use the plan. From 80% a ring turns red, and once its limit is used up it shows an exclamation mark on the status bar's error background. The weekly ring follows whichever weekly limit is most used, so a single model's limit (such as Weekly limit, Fable) shows there when it runs out first.
Hover either ring for the detail of every limit /usage lists: how much of it is used, and at what time it resets. The chip's hover shows the same detail under the sessions. Click a ring, or run Agent Watch: Show Usage Limits, for the same list with how long until each limit resets.
The figures are the last reading Claude Code took, which it keeps in its global config (~/.claude.json). Claude Code only takes a new reading now and then, so the hover says when it was taken, and the rings dim once it is over 30 minutes old. A red ring stays red, though: a limit's use only grows until it resets, so it is used at least that much. A limit whose window started over since the reading shows a dimmed question mark, since nothing says yet how much of the new one is used. With no reading, such as when Claude Code is signed in with an API key, the rings are hidden. They stay when agentWatch.hideWhenEmpty hides the chip, since the usage left matters most before starting an agent. agentWatch.showUsage turns them off, and their colors can be changed in workbench.colorCustomizations (agentWatch.usage.session, agentWatch.usage.weekly and agentWatch.usage.high); light themes get deeper shades.
The robot in the activity bar opens the Agent Watch panel: every session in one tree, with a badge counting the agents working.
- Expand a session to see what it is doing, its folder and the files it edited, with the lines added and removed (or new, deleted, no changes). Changes are measured from where the work started, so what the session already committed counts too: on a branch, from where it left the default branch (
main,masterororigin's HEAD); on the default branch itself, from where HEAD was when the session started; failing both, from HEAD. The Files edited row says which (since main, since session start). A file edited and committed many times shows its final state against that starting point. - Only files inside the workspace open in VS Code are listed, or inside a git worktree of one of its repositories wherever that worktree is: agents often work in worktrees under
/tmp, and those files show with the worktree's branch (worktree feat/x). An agent's scratch files, say in/tmp, are left out. Inside a git repository a file must also be tracked (or have existed at the starting point, so files the session deleted still show), which leaves out ignored and build files, and new files until they are added to git; in a workspace without git, every file edited inside it is listed. Each file is compared with the repository it lives in, also in multi-root workspaces. - Click a file to open the diff from that starting point to the working tree; the second button on the row opens the file itself. Edits made by the session's subagents count too.
- Group by branch with the branch button in the panel's title bar (or
agentWatch.groupBy). Sessions that share a working tree land in the same group, which shows at a glance which agents may step on each other; each worktree is a group of its own. Grouping also applies to the chip (groups are separated by·), the hover and the picker.
While a session works, the hover, the picker and the panel show its latest tool call in words, read from the session's transcript: Editing auth.ts, Running: Run the tests, Searching for "login", Running a subagent: Explore the API. Until it calls a tool it shows Thinking…; while it waits, what it waits for. Activity updates every few seconds.
When a session in this window stops to wait for your decision, a notification says which one and what it needs, with an Open button that takes you to it. Turn Off in the notification (or agentWatch.notifyOnWaiting) disables them.
The images are mockups drawn by docs/render.js with made-up sessions, using VS Code's icons and Dark Modern colors.
Agent Watch only takes you to sessions that already exist; it never starts one. Clicking a session shows it in Claude Code:
- If it is open in a tab, or in Claude Code's sidebar, it is shown there.
- Otherwise it reopens in a tab from its transcript, with its whole conversation.
Chats that have no messages yet are hidden (set agentWatch.showEmptySessions to see them) and never opened: Claude Code cannot restore an empty chat, and asked to, it starts a new one instead. Your Claude Code settings are never touched.
Sessions you archive in Claude Code are hidden too while they are idle, a few seconds after you archive them, even though their process keeps running. They come back while they work or wait for you, marked archived in the hover. Set agentWatch.showArchivedSessions to keep seeing them.
Sessions running in an integrated terminal focus that terminal instead.
A sound plays when a session in this window changes state, so you can look away while agents work:
| When | Sound | Hear it with | Turn it off | Use your own .wav |
|---|---|---|---|---|
| It finishes its turn (working → idle) | "blip" | Agent Watch: Play Finish Sound | agentWatch.soundOnFinish |
agentWatch.finishSoundFile |
| It needs your decision (working → waiting), such as a permission request | A short alert | Agent Watch: Play Waiting Sound | agentWatch.soundOnWaiting |
agentWatch.waitingSoundFile |
Several sessions changing at the same moment make one sound, and if one finishes while another starts waiting, only the waiting sound plays. Each window only sounds for its own sessions.
To tell which session a blip came from, the chip says for 10 seconds which one finished and how long it worked, such as ✓ 3 feat/login · 31 min (3 is its number in the hover and the picker), until it starts working again. Clicking the chip then opens the picker on it. With the workspace or all scope it also does so for sessions of other windows, which make their sound there. Turns shorter than agentWatch.minTurnSeconds finish quietly: no blip, no notification, nothing in the chip.
While a window is minimized or behind another one, its sessions also show a system notification when they finish or need your decision, with the session's title, how long it worked or what it waits for, and its folder. Agent Watch shows them with notify-send on Linux (in the libnotify-bin package) and Notification Center on macOS; agentWatch.desktopNotifications turns them off. Sounds are played with the system player (pw-play, paplay or aplay on Linux, afplay on macOS). The finish blip is generated by scripts/make-sounds.js; the waiting sound is a recording by another author (see Credits).
Each agent is read by a provider (see Adding an agent). For Claude Code:
- Sessions: Claude Code writes one record per running session to
~/.claude/sessions/<pid>.json(or$CLAUDE_CONFIG_DIR/sessions) with itsstatus(busy,waiting,idle),cwdand start time. The extension watches that directory and re-checks every 5 seconds. It only reads the.jsonrecords, never the.keyfiles next to them. - Titles, activity and edited files: read from the session's transcript in
~/.claude/projects/and its subagents' transcripts. Each refresh reads only what was appended since the last one. - Archived sessions: archiving a chat leaves its record in place; the Claude Code extension only adds its id to its own VS Code state (
hiddenSessionIds). Extensions cannot read each other's state through the VS Code API, so Agent Watch reads it, read-only, from the database where VS Code keeps it (state.vscdbin the profile'sglobalStoragefolder), with Node's built-in SQLite module, and only again when that file changes. - Usage limits: each time Claude Code fetches the plan's usage, it caches it in
~/.claude.json(or$CLAUDE_CONFIG_DIR/.claude.json) undercachedUsageUtilization. Agent Watch reads every limit from there (thelimitslist/usageshows, or the olderfive_hourandseven_dayfields), only again when the file changes, and never asks for them online or touches Claude Code's credentials. - Branches and changes: the branch comes from the folder's
.git(worktrees included) without running git; line counts and diffs rungit status,git diffandgit show, only when the panel asks.
And for every agent:
- Liveness: a session whose process is gone, or whose PID was reused by another process, is ignored.
- Which window owns a session (Linux): chats opened by an agent's VS Code extension are child processes of the window's extension host; CLI sessions descend from one of the window's terminal shells. The extension walks
/procto tell them apart.
Nothing leaves the machine: no network calls, no telemetry.
- It never starts a session. Only sessions with a transcript are handed to Claude Code, in the mode that reveals or restores them rather than the sidebar route, which opens a new empty chat when Claude Code's sidebar is closed. Clicks are handled one at a time.
- Nothing blocks VS Code. Files are read asynchronously; a terminal that never reports its process, a refresh that hangs or an audio player that gets stuck are all cut off after a timeout.
- Odd data is skipped, not shown. Half-written records, invalid fields, records from another machine or PID namespace (a dev container sharing
~/.claude), dead processes and reused PIDs are ignored. Two processes on the same session show as one dot. Titles are escaped before they reach the hover, which runs trusted command links. - Invalid settings fall back to their defaults.
- Problems are written to the Agent Watch output channel (Agent Watch: Show Log), once per distinct problem.
| Setting | Default | Description |
|---|---|---|
agentWatch.scope |
window |
window: sessions started from this window. workspace: also others inside this workspace. all: every session on the machine. |
agentWatch.showEmptySessions |
false |
Also show chats that have no messages yet. They are never opened from here. |
agentWatch.showArchivedSessions |
false |
Also show idle sessions you archived in Claude Code. They always show while they work or wait. |
agentWatch.soundOnFinish |
true |
Play a blip when a session in this window finishes its turn. |
agentWatch.soundOnWaiting |
true |
Play an alert when a session in this window waits for your decision. |
agentWatch.finishSoundFile |
(empty) | .wav file to play instead of the built-in finish blip. |
agentWatch.waitingSoundFile |
(empty) | .wav file to play instead of the built-in waiting sound. |
agentWatch.minTurnSeconds |
0 |
Turns shorter than this finish quietly: no blip, no system notification, no mention in the chip. |
agentWatch.notifyOnWaiting |
true |
Show a notification with an Open button when a session in this window waits for your decision. |
agentWatch.desktopNotifications |
true |
While this window is minimized or in the background, show a system notification when one of its sessions finishes or waits for you. |
agentWatch.order |
stable |
stable: start order, every dot keeps its place. status: waiting first, then working, then idle. |
agentWatch.groupBy |
none |
branch: keep sessions in the same branch or worktree together in the chip, hover, picker and panel. |
agentWatch.icon |
agent-watch-robot |
Icon at the start of the chip: the extension's robot, or any codicon such as robot or sparkle. |
agentWatch.iconReflectsStatus |
true |
Color the icon with the most urgent status. |
agentWatch.maxDots |
8 |
Dots shown before the rest are grouped as +N. |
agentWatch.hideWhenEmpty |
false |
Hide the chip when no sessions are running. The usage rings stay. |
agentWatch.showUsage |
true |
Show how much of the plan's 5-hour and weekly usage limits is used as two rings after the chip, with the percent inside and every limit in their hover. |
agentWatch.dots |
🟡 🔴 🟢 |
Character for each status (busy, waiting, idle). |
Sessions that belong to another window or to a terminal outside VS Code are shown with the workspace and all scopes, but are not opened from here: attaching a second client to a running session would conflict with it.
Everything specific to an agent lives in a provider under src/providers/. A provider lists its sessions in a shared shape (process, folder, status, what it waits for), describes each one (title, current action, edited files, branch) and, if the agent has a VS Code extension, opens a session in it. The chip, hover, picker, panel, sounds and notifications work from those fields alone. src/providers/index.js documents the interface and registers the providers; src/providers/claude-code/ is the reference implementation.
- Claude Code's session records, transcripts and usage cache are internal formats, not a documented API. If an update changes them, sessions, their activity or the usage rings may stop showing; Claude Code itself is unaffected.
- So is the way Claude Code and VS Code store archived sessions. Archived sessions keep showing where it cannot be read: VS Code versions whose Node has no built-in SQLite module, and remote windows (SSH, WSL, dev containers), whose extension state stays on the local machine.
- A status bar item takes a single text color and a single click target. That is why the dots are emoji, why each usage ring is a status bar item of its own, and why sessions are opened from the hover or the picker rather than by clicking an individual dot.
- Window ownership needs
/proc(Linux). Elsewhere, sessions inside the workspace folders count as this window's.
From the Visual Studio Marketplace: search for Agent Watch in the Extensions view, or run
code --install-extension csantosm.agent-watch-statusYou need node (18 or later, with npx) and VS Code's code command:
git clone https://github.com/CSantosM/agent-watch.git
cd agent-watch
./package.sh --installpackage.sh builds the .vsix with the official packager, vsce, which runs the tests first and refuses to package if any fails. Then run Developer: Reload Window in each open VS Code window. To uninstall: code --uninstall-extension csantosm.agent-watch-status.
| Path | What it holds |
|---|---|
extension.js |
Everything that talks to VS Code: the chip, hover, picker, notifications and opening sessions and files |
src/panel.js |
The Agent Watch panel |
src/providers/ |
One provider per agent; claude-code/ reads Claude Code's records and transcripts and opens its chats |
src/sessions.js |
Provider-neutral checks: liveness, window ownership, machine, deduplication |
src/git.js |
Branches, worktrees, file changes and HEAD contents |
src/sound.js |
The finish and waiting sounds and their audio player fallbacks |
src/util.js |
Formatting and timeout helpers |
test/ |
node:test suites; test/helpers.js stands in for the vscode module |
package.sh |
Tests and packages the extension with vsce (--install also installs it) |
docs/render.js |
Draws the README images in docs/images with headless Chrome (node docs/render.js) |
scripts/make-icons.py |
Draws the robot once and writes the status bar font glyph, the activity bar icon and the extension icon, the last two with the three status dots, plus the usage rings in the same font and their entries in package.json (python3 scripts/make-icons.py; needs fontTools and Chrome) |
l10n/ |
Translations of the extension's own texts (bundle.l10n.<language>.json) |
scripts/make-sounds.js |
Synthesizes the finish blip |
.github/workflows/release.yml |
Releases a new version to the Marketplace and GitHub (see Releasing) |
scripts/stamp-changelog.js |
Turns the ## Unreleased section of the changelog into the release's section; used by the release workflow |
Run the tests with npm test (or node --test 'test/*.test.js'). The extension tests start real sleep processes to stand in for Claude sessions, so they need Linux.
- While working, list the changes under a
## Unreleasedheading at the top ofCHANGELOG.md. - In GitHub, open Actions › Release › Run workflow, keep the branch on
mainand choose the part of the version to increase:patch,minorormajor. Tick dry_run to check the sign-in, test and package without publishing anything.
The workflow renames ## Unreleased to ## <version> (<date>), packages the extension (running the tests), publishes it to the Visual Studio Marketplace, pushes the commit Agent Watch <version> and the tag v<version> to main, and creates the GitHub release with the .vsix and the changelog section as its notes. It stops before changing anything if the ## Unreleased section is missing or empty, or if it cannot sign in to the Marketplace. If it fails before pushing the tag, run it again: it releases the same version, and skips publishing it if the Marketplace already has it.
The job runs in the marketplace environment and signs in to the Marketplace with one of:
- Microsoft Entra ID (preferred, no secret to store):
- In Azure, create a user-assigned managed identity and add it a federated credential for GitHub Actions deploying Azure resources: organization
CSantosM, repositoryagent-watch, entity Environment, environmentmarketplace. - In GitHub, set the repository variables
AZURE_CLIENT_IDandAZURE_TENANT_IDto the identity's client ID and tenant ID. - Run the workflow with dry_run. The step Check the Marketplace sign-in prints the identity's Azure DevOps ID (and fails, because the identity cannot publish yet).
- In the Marketplace publisher page, add that ID as a member with the Contributor role. The next dry run passes.
- In Azure, create a user-assigned managed identity and add it a federated credential for GitHub Actions deploying Azure resources: organization
- A personal access token: an Azure DevOps token for All accessible organizations with the Marketplace › Manage scope, in the repository secret
VSCE_PAT. Azure DevOps retires these global tokens on 2026-12-01; use Entra ID after that.
If both are set, the workflow uses Entra ID.
The code is under the MIT License.
media/waiting.wav, the waiting sound, is "Gunpoint" by LilMati on Freesound, released under CC0. The file's own metadata names Mattias "MATRIXXX" Lahoud and a Creative Commons Attribution license, so it is credited here either way.




