Agent inventory (Alpha)
Agent inventory is a best-effort list of the agents found on machines running the Watcher client and in traffic through your gateway. Use it to shape your agent adoption strategy. It does not replace a full MDM.
What it shows
The inventory answers three questions:
- Which coding agents are installed and used on machines that run the Watcher client.
- Whether Watcher receives sessions from the people who use those agents (coverage, below).
- Which clients send traffic through Watcher's gateway hooks: the Tailscale Aperture hook, and the raw format of the generic pre-tool-use hook that LiteLLM and other gateways use (see gateway hooks).
It is for planning which agents to support, monitor or retire. It is not a device-management tool, it does not block or allow any agent, and it is not built to find an agent that someone deliberately hides. It reads where agents are installed and how recently they were used; it never reads what anyone did with them.
Turning it on and off
Agent inventory is off by default. One
managed client settings
key controls it, agent_inventory.enabled:
agent_inventory:
enabled: true
The switch on the agent inventory page of the Analyzer sets this
key in your organization's saved settings document. You can also set it in the
Managed Settings editor. Both need the org:settings:write permission. On a
self-hosted deployment, each change is recorded in the
admin audit log as an organization settings write.
The key is admin-only. A client reads it only from the organization's settings
on its machine (the admin settings baseline), never from a developer's own
settings file or a profile, so locking it adds nothing. Someone who edits the
baseline file on their own machine changes only that machine, until the next
settings delivery replaces the file, and the deployment still refuses reports
while its own copy is off. Any value other than true, or no value, means off.
The enabled: {value: true, permission: locked} form is accepted too, but the
lock changes nothing.
Two places read the key. Your Watcher deployment reads the organization's saved document, or its settings file when it supplies one, and refuses inventory reports and gateway sightings unless that copy turns inventory on. Each Watcher client reads the settings file on its machine, and scans only while that file turns inventory on. How you distribute settings decides where to set the key:
- "Distribute via Watcher" on. Save the key once. Each client pulls the document within a few minutes and normally notices the setting within about 15 minutes after that. Scanning starts at its next scheduled scan, and a retry delay from an earlier refused report still applies.
- Settings distributed by your MDM. Save the key in the Analyzer settings
editor, and ship that saved document in the settings file your MDM delivers
(
~/.apollo_monitor/settings.yaml). Clients normally notice the change within about 15 minutes and scan at their next scheduled scan. If only the shipped file turns it on, clients scan but the deployment refuses every report. If only the Analyzer copy turns it on, clients scan nothing, but gateway hooks still record sightings. - A self-hosted deployment that supplies the document from a file. Set the key in that file. The Analyzer switch cannot save while the file is in force. See Supplying the document from your deployment.
While inventory is off:
- Watcher clients scan nothing and send nothing.
- The server refuses inventory reports. A client that still sends one tries again at its next hourly scan.
- Gateway hooks record no sightings.
- Nothing is deleted. Stored reports and sightings stay, and the inventory endpoints still return them. The Analyzer page says that inventory is off and keeps showing the stored data.
Turning inventory on or off does not change Watcher's hooks or session recording.
How the client finds agents
The Watcher client looks in the well-known places each agent installs to: its
command-line installer folder, npm and other Node package managers' global
folders, Homebrew, uv tool and pipx, editor extension folders, macOS
application bundles, and the agent's own configuration folder. It scans about
once an hour and sends every scan as a report. A report that fails is retried a
few times, then dropped; the next scan sends a fresh one.
Editor extensions keep their session files in the editor's own storage, so the client reads them in VS Code, VS Code Insiders, Cursor, Windsurf and VSCodium, and on remote VS Code and Cursor servers. GitHub Copilot chat sessions count only in VS Code, VS Code Insiders, VSCodium and remote VS Code servers, because other editors can keep their own assistants' chats in the same format.
Agents that let you move their configuration folder are found there too, for
example through CLAUDE_CONFIG_DIR, CODEX_HOME or COPILOT_HOME. The client
reads these variables from its own environment. A variable set only in an
interactive shell is not visible to it, so an agent configured that way may be
reported without its sessions.
Session files are counted from their names and modification times. The client
never opens them. It reads small package and application metadata files, such
as package.json and Info.plist, to find versions. To report whether
Watcher's hooks are on for Claude Code, Codex or GitHub Copilot CLI, it looks in
that agent's hook configuration for Watcher's own hooks, without changing it. A
Watcher skill or status line alone does not count. Only the hook state is
reported. It skips network filesystems, never touches the macOS Desktop,
Documents, Downloads, Movies, Music, Pictures or iCloud Drive folders, never
scans as root, and does not report when the client uses an organization API key.
| Agent | ID | Kind | What inventory reports | Monitored through |
|---|---|---|---|---|
| Claude Code | claude_code | CLI, IDE extension, SDK | Installs, recent use and Watcher hooks | Watcher client or gateway hook |
| Codex | codex | CLI, desktop app, IDE extension | Installs, recent use and Watcher hooks | Watcher client or gateway hook |
| GitHub Copilot CLI | github_copilot_cli | CLI | Installs, recent use and Watcher hooks | Watcher client or gateway hook |
| Gemini CLI | gemini_cli | CLI | Installs and recent use | Gateway hook or SDK example |
| Qwen Code | qwen_code | CLI | Installs and recent use | Gateway hook or SDK example |
| OpenCode | opencode | CLI | Installs only | Gateway hook or SDK example |
| Antigravity | antigravity_cli | CLI, desktop app, IDE, IDE extension | Installs only | Gateway hook |
| Mistral Vibe | mistral_vibe | CLI | Installs and recent use | Gateway hook or SDK example |
| Pi | pi | CLI | Installs and recent use | Gateway hook or SDK example |
| OpenClaw | openclaw | CLI | Installs and recent use | SDK example |
| Hermes Agent | hermes | CLI | Installs only | SDK example |
| OpenHands | openhands | CLI | Installs and recent use | SDK example |
| Kilo Code | kilo_code | CLI, IDE extension | Installs only | SDK example |
| Crush | crush | CLI | Installs only | Not supported |
| Goose | goose | CLI | Installs only | SDK example |
| Aider | aider | CLI | Installs only | SDK example |
| Amp | amp | CLI | Installs only | SDK example |
| Factory Droid | factory_droid | CLI | Installs only | Not supported |
| Augment | augment | CLI, IDE extension | Installs and recent use | Not supported |
| Continue | continue_cli | CLI, IDE extension | Installs and recent use | SDK example |
| Cline | cline | CLI, IDE extension | Installs and recent use | SDK example |
| Roo Code | roo_code | IDE extension | Installs and recent use | SDK example |
| Amazon Q | amazon_q | IDE extension | Installs only | Not supported |
| Gemini Code Assist | gemini_code_assist | IDE extension | Installs only | Not supported |
| GitHub Copilot in VS Code | vscode_github_copilot | IDE, IDE extension | Installs and recent use | Not supported |
| Cursor | cursor | CLI, IDE | Installs and recent use | SDK example |
| Windsurf | windsurf | IDE | Installs only | SDK example |
| Kiro | kiro | CLI, IDE | Installs and recent use | Not supported |
| Trae | trae | IDE | Installs only | Not supported |
| Claude Desktop | claude_desktop | Desktop app (macOS) | Installs only | Not supported |
| ChatGPT/Codex desktop | chatgpt_codex_desktop | Desktop app (macOS) | Installs only | Not supported |
"What inventory reports" is how much the Watcher client reports about the agent on a machine. Every agent's installs and versions are reported. "Recent use" adds the day it was last used and how many of its session files changed in the last 7 days, from the agent's own session store. "Watcher hooks" adds whether Watcher's hooks are on for it. An agent reported as "Installs only" never has a last-used date, so it never shows a coverage gap.
"Monitored through" names a connection that lets inventory match that agent's sessions. See supported agents for built-in support, and Integrations for the SDK examples and their limits. An SDK example's sessions count toward coverage once the example is installed and sends sessions with its own conversation prefix. Hermes Agent, and OpenClaw sessions stored only in a database, are detected, but their recent use is unknown. An agent's directory overrides must be set in the Watcher client's environment to be found.
The Codex desktop app is the Codex CLI that the ChatGPT desktop app bundles; the ChatGPT/Codex desktop row is the desktop app itself.
Non-coding agents and other tools
The Watcher client finds the agents listed above, including general-purpose
agents such as OpenClaw and Hermes that can be used for coding. Other tools
appear only if their traffic goes through one of the gateway hooks
above. A gateway sighting is filed under the agent's name when Watcher
recognizes the agent from its user agent. Otherwise it is filed under the
product name the user agent starts with. For example,
Custom AI App Python/1.4.2 (Python 3.12; Linux) appears as
custom-ai-app-python, and a request with no user agent appears as unknown.
A product name that matches an agent's ID without Watcher recognizing that
agent gets -client added, so Pi/2.0 appears as pi-client and is never
counted as the Pi coding agent.
Chat in a web browser is not covered.
Coverage
Coverage says whether Watcher receives the sessions of an agent someone uses. It applies to each person and agent with use in the last 7 days:
| State | Meaning |
|---|---|
| Monitored | Watcher has at least one session from this person for this agent with activity in the last 7 days, through the Watcher client, a gateway hook or a registered SDK example. |
| Gap | The agent has a connection listed above, the person used it in the last 7 days, and Watcher has no such session. |
| Not supported | The agent table marks it "Not supported", so coverage is not checked. |
An agent counts as used by a person when any of three sources shows it in the last 7 days: a report from their Watcher client, sessions Watcher received from them, or gateway traffic. Gaps come only from Watcher client reports, so a person without the Watcher client, or whose client uses an organization API key, never shows a gap. Sessions count only for people the inventory already lists through a reporting machine or the gateway. An agent reported without a last-used date does not count as used on that machine and gets no coverage state from it. Agents marked "Installs only" in the table above are always reported that way. Unless Watcher received sessions for them, the Analyzer shows "Use not detected" for them rather than treating them as unused. An agent Watcher received sessions for in the last 7 days shows as monitored, even when no machine reports using it. Coverage is worked out each time the inventory is read, from each machine's latest report and the sessions Watcher has received up to that moment. The last 7 days are counted back from that read. Coverage is per person, because sessions belong to people, not machines. A person with one machine that sends sessions and one that does not counts as monitored.
The inventory page counts people seen in the last 7 days through the Watcher
client or a gateway hook, once each however many machines they use, and each
count opens a list of those people. To list the people with a gap, open "Users
missing coverage", or call GET /v1/agent-inventory/users?coverage=gap.
On a machine's or a person's page, a gap shows as "Missing" with its likely
reason, from the Watcher hook state on the person's machines: "hooks off",
"Watcher turned off on the machine", "hooks on, nothing received", or, for an
agent Watcher has no hooks for, "nothing from a gateway or SDK". Next to it,
the sessions column compares the sessions Watcher received in the last 7 days
with the session files the person's machines found, for example "0 of 58
received". On a machine's page it counts only the person's sessions recorded
with that machine's hostname. Sessions through a gateway or SDK record no
hostname, so they count only on the person's page, and a person's machines with
the same hostname share one count. The two counts are measured differently
(sessions that ended, against files changed), so the percentage is a rough guide
and can pass 100%. For agents monitored
through the Watcher client, common causes are hooks never set up, the agent
turned off with watcher agents disable or by your organization, an agent
started with another configuration folder or with options that skip hooks, and a
stopped or signed-out client. For agents monitored through a gateway hook or an
SDK example, the gap shows "nothing from a gateway or SDK", usually because the person's
traffic for that agent skips the gateway or its SDK example is not recording
sessions. Repositories excluded with a
.watcher-ignore file also look like gaps: their sessions are deliberately not uploaded.
Gateway sightings
While inventory is on, the Aperture hook and the raw format of the pre-tool-use hook record sightings of the clients that send requests, including traffic Watcher does not otherwise record. Other ways of sending sessions to Watcher record no sightings. A sighting stores the person (a gateway login name or a caller's email), the client name, the person's Watcher user and when the request arrived. Each person and client is recorded at most once every five minutes, and a client that sends no requests records nothing.
Who the person is depends on the credential the gateway uses:
- When the caller holds
sessions:write:any, the person is the login name the gateway sends, and that login becomes a Watcher user. This is the same rule the gateway hooks use when they record a session. If no user has that email yet, Watcher creates one, and the person gets that same user when they first sign in with that email. - Otherwise the person is the caller's own Watcher user.
- Requests that name nobody are recorded together as one person, listed as
gateway:no-identity.
Users created this way are listed with your organization's other users, for
example in GET /v1/users, before they ever sign in. This includes people
whose gateway traffic Watcher never records, such as non-coding apps routed
through the gateway.
A sighting never stores request or response bodies, raw user agents, URLs, providers, models, request IDs, device identifiers, token counts or request counts. Sightings are saved in the background: a hook never waits for one, and its response never changes. A sighting that fails to save is not retried; the next request from that person and client records it.
Report fields
Each Watcher client report contains:
- A random installation ID, which identifies one Watcher client install for one operating-system user on one machine.
- When the scan ran.
- The client version, hostname, operating system and architecture.
- For each agent found: where it is installed (CLI, IDE, IDE extension, desktop app or SDK), its version when it can be read cheaply, and Watcher's hook state for it: on, off, disabled (Watcher turned off) or not applicable. An agent whose settings folder is all that was found, with nothing installed and no session files, is marked as such: someone set it up on the machine once, and it may since have been removed.
- For each agent, when the client can count its session files: the UTC date it was last used and how many of its session files changed in the last 7 days. Some agents, including OpenCode and Antigravity, never have these, and any agent can lack them when its session folders are too large to list.
The report is attributed to the person signed in to the Watcher client when the install first reports, and the install stays theirs. It never contains prompts, transcripts, file contents, settings values, provider or model names, or credentials.
Every hourly report is stored as its own record. The inventory shows each machine's latest report.
Who can see what
| Data | Required permission |
|---|---|
| Whether inventory is on, in the Analyzer or the managed settings API | org:settings:read. |
| Turning inventory on or off | org:settings:write. |
| Organization-wide counts, coverage and gateway sightings | Both org:settings:read and sessions:aggregates:read:any. Counts only, with no names or email addresses. |
| People, their machines and agents | Both org:settings:read and sessions:findings:read:any. Other people's email addresses and gateway login names also need users:read:any. |
With the default roles, only admins can see inventory data. On a self-hosted deployment, each request for the people or machine list is recorded in the admin audit log. See permissions for the endpoints.
Retention and deletion
Agent inventory does not delete anything yet. Every report from each machine and every gateway sighting is kept, including after inventory is turned off. The only deletion is through users: deleting a user also deletes their machines, those machines' reports and their sightings.
A machine whose latest report is more than 90 days old is hidden from the Analyzer and the inventory endpoints, but not deleted. If it reports again, it reappears with its original first-report date.
On a self-hosted deployment, plan database storage for this: each machine with inventory on adds one report an hour while its client runs, and each person adds up to one sighting per client every five minutes while they use the gateway.
The CLI
| Command | What it does |
|---|---|
watcher inventory show | Scans the machine now and lists the agents found. Then it prints the installation ID ("not assigned yet" before the install first reports; show never assigns one), whether this machine's settings turn inventory on, and, for the Watcher deployment the client points at, when the background client last scanned, last had a report accepted and scans next. --json prints only the current local scan. Nothing is uploaded, and it works whether or not inventory is on. It runs with your terminal's environment, which can include configuration-folder variables the background client does not see. |
watcher inventory reset-id | Gives the install a new installation ID, for example on a machine cloned from an image. If a report is being sent, it waits for it to finish, so no later report uses the old ID. |
Both commands refuse to run as root.