Skip to main content
Working with an agent? Give them a link to this page as markdown.

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.

AgentIDKindWhat inventory reportsMonitored through
Claude Codeclaude_codeCLI, IDE extension, SDKInstalls, recent use and Watcher hooksWatcher client or gateway hook
CodexcodexCLI, desktop app, IDE extensionInstalls, recent use and Watcher hooksWatcher client or gateway hook
GitHub Copilot CLIgithub_copilot_cliCLIInstalls, recent use and Watcher hooksWatcher client or gateway hook
Gemini CLIgemini_cliCLIInstalls and recent useGateway hook or SDK example
Qwen Codeqwen_codeCLIInstalls and recent useGateway hook or SDK example
OpenCodeopencodeCLIInstalls onlyGateway hook or SDK example
Antigravityantigravity_cliCLI, desktop app, IDE, IDE extensionInstalls onlyGateway hook
Mistral Vibemistral_vibeCLIInstalls and recent useGateway hook or SDK example
PipiCLIInstalls and recent useGateway hook or SDK example
OpenClawopenclawCLIInstalls and recent useSDK example
Hermes AgenthermesCLIInstalls onlySDK example
OpenHandsopenhandsCLIInstalls and recent useSDK example
Kilo Codekilo_codeCLI, IDE extensionInstalls onlySDK example
CrushcrushCLIInstalls onlyNot supported
GoosegooseCLIInstalls onlySDK example
AideraiderCLIInstalls onlySDK example
AmpampCLIInstalls onlySDK example
Factory Droidfactory_droidCLIInstalls onlyNot supported
AugmentaugmentCLI, IDE extensionInstalls and recent useNot supported
Continuecontinue_cliCLI, IDE extensionInstalls and recent useSDK example
ClineclineCLI, IDE extensionInstalls and recent useSDK example
Roo Coderoo_codeIDE extensionInstalls and recent useSDK example
Amazon Qamazon_qIDE extensionInstalls onlyNot supported
Gemini Code Assistgemini_code_assistIDE extensionInstalls onlyNot supported
GitHub Copilot in VS Codevscode_github_copilotIDE, IDE extensionInstalls and recent useNot supported
CursorcursorCLI, IDEInstalls and recent useSDK example
WindsurfwindsurfIDEInstalls onlySDK example
KirokiroCLI, IDEInstalls and recent useNot supported
TraetraeIDEInstalls onlyNot supported
Claude Desktopclaude_desktopDesktop app (macOS)Installs onlyNot supported
ChatGPT/Codex desktopchatgpt_codex_desktopDesktop app (macOS)Installs onlyNot 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:

StateMeaning
MonitoredWatcher 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.
GapThe agent has a connection listed above, the person used it in the last 7 days, and Watcher has no such session.
Not supportedThe 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​

DataRequired permission
Whether inventory is on, in the Analyzer or the managed settings APIorg:settings:read.
Turning inventory on or offorg:settings:write.
Organization-wide counts, coverage and gateway sightingsBoth org:settings:read and sessions:aggregates:read:any. Counts only, with no names or email addresses.
People, their machines and agentsBoth 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​

CommandWhat it does
watcher inventory showScans 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-idGives 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.