Agent detection
detectAgents reports runnable, found, missing or unknown, with evidence and login state.
Status and probes
@rivus/agent-kit/discovery exports detectAgents, versionFromOutput and ProbeRecipe. It runs anywhere, with a platform.
detectAgents(platform) reports, for each built-in Agent in the Agents table, whether it is runnable, found, missing or unknown, with the evidence, the version its command printed and the login state.
By default the login state comes only from credential files and environment variables, without running anything and without returning secret values. authProbe: "commands" also runs the Agents' own status commands, whose side effects each recipe lists.
Version probes run by default and make an Agent runnable. versionProbe: false runs nothing at all. Only a successful version probe establishes runnable.
Commands run without a shell and with a time limit. A check that fails is reported in problems. detectAgents resolves to Installation[]. A failed probe is recorded in that Agent's problems.
builtinProviders has an identity for each of them, and a home rule for each one except Cursor.
What counts as found
detectAgents reports found from a command on PATH, an application path, or an Agent-owned state path.
Configuration evidence uses the existing config kind. Its paths are session stores, application state or credential files, not arbitrary configuration. An empty store still counts, and retained state can establish found after the command is removed.
An installer can create an Agent home and populate hooks, settings, MCP servers, skills, plugins or extensions without installing the Agent. None of those paths establishes found. Built-in mcpConfigPaths are empty because the previously listed MCP files are shared, installer-writable configuration. In particular, ~/.claude.json can contain MCP configuration: it remains a source of login state when other evidence exists, but its existence alone is not installation evidence. Auth variables also do not establish installation.
Configuration evidence comes from Agent-owned session stores, application state or credential files. Agent homes and shared hook/MCP settings, plugins, extensions and skills do not count: installing hooks alone leaves an Agent missing.
The table lists every built-in configuration evidence path. Agent-home paths use catalog rules. An override replaces the default home, rather than probing both. The session/usage fixtures validate the layouts without reading any local Agent data. Credential paths come from the existing login probes. Discovery returns only non-secret authentication facts.
| Agent | Evidence relative to its data home | Home and overrides | Sources and reason |
|---|---|---|---|
| Claude Code | projects/, .credentials.json | ~/.claude; CLAUDE_CONFIG_DIR replaces it | Session layout stores project transcripts; credential probe identifies the CLI login file. |
| Codex | sessions/, archived_sessions/, auth.json | ~/.codex; CODEX_HOME replaces it | Session layout reads active and archived rollouts; credential probe reads stored login state. |
| Gemini CLI | tmp/, oauth_creds.json | ~/.gemini; GEMINI_CLI_HOME replaces the parent, yielding $GEMINI_CLI_HOME/.gemini | Session layout reads chats beneath tmp; credential probe names OAuth storage. |
| Grok | sessions/, auth.json | ~/.grok; GROK_HOME replaces it | Session layout reads session updates and metadata; credential probe reads scoped credentials. |
| opencode | opencode.db, storage/message/, auth.json | ~/.local/share/opencode; $XDG_DATA_HOME/opencode when set | Usage decoder reads SQLite and legacy message storage; credential probe reads provider logins. This is the data home, not the plugin/config home. |
| Pi | sessions/ | ~/.pi/agent; PI_CODING_AGENT_DIR replaces it and expands a leading ~ | Session layout reads session JSONL. |
| DeepSeek Harness | sessions/, .credentials.yaml | ~/.dsh; DSH_HOME replaces it and expands a leading ~ | Session layout reads session logs; the credential probe checks that the stored YAML credential file exists, without reading it. |
| Cursor | User/globalStorage/ beneath each desktop root; ~/.config/cursor/auth.json, ~/AppData/Roaming/Cursor/auth.json | Desktop roots: ~/Library/Application Support/Cursor, ~/.config/Cursor, ~/AppData/Roaming/Cursor; fixed CLI credential locations; no catalog home rule | Cursor support identifies the desktop state database in globalStorage. The credential probe identifies Linux/Windows CLI login storage; macOS uses the keychain. CURSOR_CONFIG_DIR and XDG_CONFIG_HOME remain unsupported. |
Pi remains session-only: the kit has no Pi authentication probe or documented authentication file.
Provider home rules and homeFromRule own override resolution. Usage source tests cover all six default layouts and overrides using the providers' usage fixtures: Claude Code, Codex, Gemini CLI, Grok, opencode and Pi. Discovery's evidence regression tests check each path independently and run planInstall / applyInstall over an in-memory home before detection.
Paths that are not evidence
Harness artifacts and shared configuration remain excluded:
| Agent | Paths excluded from evidence | Source |
|---|---|---|
| Claude Code | skills/, settings.json | Strategies |
| Codex | plugins/, config.toml, hooks.json, shared skills | Strategies |
| Gemini CLI | extensions/, settings.json | Strategies |
| Grok | hooks/ | Strategies |
| opencode | $XDG_CONFIG_HOME/opencode/plugins/ (default ~/.config/opencode/plugins/), opencode.json(c) | Strategies |
| Pi | extensions/, settings.json | Strategies |
| Cursor | ~/.cursor/, ~/.cursor/plugins/local/, the three desktop roots' User/mcp.json | Strategies |
Changing these facts affects consumers of detectAgents with the built-in recipes, including agent-presence and application setup/detection screens. Machines with no command, recognized application or Agent-owned state now report missing, including Claude Code with only ~/.claude.json (macOS keychain login and no session yet), and machines populated only by hooks or MCP settings. Cursor desktop state still establishes found without a CLI. Command and application-path detection, custom recipes, and the evidence/status interfaces remain unchanged.
To customize a built-in recipe, select its discovery service and pass providers. See Providers. Check a recipe you write with probeRecipeConformance from /testing.