Install
agent-presence runs on macOS and Linux (Windows is not supported) and needs Node.js 22.13 or newer. Credentials live in Keychain on macOS and libsecret on Linux.
If you use 0.9.0 or earlier, follow Upgrading before replacing the package.
Global install
Section titled “Global install”pnpm add -g @rivus/agent-presenceagent-presence setupnpm i -g @rivus/agent-presenceagent-presence setupbun add -g @rivus/agent-presenceagent-presence setupAgent detection
Section titled “Agent detection”setup detects the six supported agents: claude-code, codex, gemini-cli, grok, opencode and pi. It selects agents reported as found or runnable. Detection checks only whether commands on PATH or agent-owned session/state stores and credential files exist. It does not run agent commands or read credential contents, so detection alone cannot establish runnable.
The default agent-owned evidence paths are:
| Agent | Evidence paths |
|---|---|
| Claude Code | ~/.claude/projects/, ~/.claude/.credentials.json |
| Codex | ~/.codex/sessions/, ~/.codex/archived_sessions/, ~/.codex/auth.json |
| Gemini CLI | ~/.gemini/tmp/, ~/.gemini/oauth_creds.json |
| Grok | ~/.grok/sessions/, ~/.grok/auth.json |
| opencode | ~/.local/share/opencode/opencode.db, ~/.local/share/opencode/storage/message/, ~/.local/share/opencode/auth.json |
| Pi | ~/.pi/agent/sessions/ |
CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME and PI_CODING_AGENT_DIR replace the corresponding default homes. GEMINI_CLI_HOME replaces Gemini’s parent directory, so its evidence lives under $GEMINI_CLI_HOME/.gemini/. opencode uses $XDG_DATA_HOME/opencode/ when set; detection checks this data home, not its plugin/config home.
An empty session store counts, and retained agent-owned state can establish found after the executable is removed. An agent home alone, presence hooks/plugins, shared settings and MCP configuration do not count, so running presence setup does not make an otherwise missing agent detectable.
For a missing agent, setup asks you to install it and run setup again. If a check cannot complete and nothing establishes that the agent is present, setup skips it as unknown, names the failed checks and points to --agents. A desktop-app-only installation whose CLI has never run and is absent from PATH requires this override. You can also use it to limit the selection. It accepts a comma-separated list of supported kit ids:
agent-presence setup --agents claude-code,codexUnknown ids and kit ids without presence support are errors. Hooks for agents omitted by detection or --agents stay unchanged. When the harness ledger has entries owned by agent-presence for those agents, setup names them and shows agent-presence setup --agents <id,...> to update them. agent-presence uninstall removes presence hooks for all agents. Install an agent later and rerun setup to add its hooks. If no agent is detected and --agents is absent, setup skips the agent install plan, confirmation, apply and verification. It still prepares the shim for the selected --hook-command mode: package installs or reuses the pinned runtime, while absolute uses the checkout CLI. Only after preparation succeeds does setup continue with the watcher, dsh and provider steps.
setup lists configuration conflicts and their allowed resolutions, re-plans with your choices, then shows the complete changes, commands and expected trust prompts. Review and confirm that plan before it writes agent configuration. Canceling, declining confirmation or encountering a protected target stops setup. Login may already have written its own data.
In a non-interactive terminal, setup --yes applies a conflict-free plan. It does not resolve conflicts automatically. An interactive terminal always asks for confirmation, including with --yes. After confirmation, setup installs or reuses the pinned runtime in package mode, writes the shim, applies the plan and immediately verifies the kit artifacts selected for this run. If runtime installation fails, it removes the temporary install, discards the plan and exits non-zero before writing the shim or any agent target. If verification fails, setup stops without installing the watcher, offering dsh, publishing to the provider or displaying a signature URL. After successful verification, or when no agent was selected, it installs the macOS power watcher, updates an existing presence dsh plugin or offers a fresh installation, and configures the provider. A canceled dsh prompt or provider failure does not skip the verification results. Linux skips the watcher and relies on TTL pruning.
Without a global install
Section titled “Without a global install”pnpm dlx @rivus/agent-presence@latest setupnpx --yes --registry=https://registry.npmjs.org @rivus/agent-presence@latest setupbunx @rivus/agent-presence@latest setup--hook-command package is the default: setup uses npm to install its exact published version into ~/.agent-presence/runtime/<version>/, then hooks run the installed CLI directly with Node. npm and access to https://registry.npmjs.org are needed only when setup installs a missing or invalid runtime; hook execution uses neither npm nor npx. --hook-command npx remains accepted as an alias for package.
To use a local checkout’s built CLI without installing a runtime, run:
node <checkout>/dist/src/cli.js setup --hook-command absoluteThe default provider is magic-builder, so the first setup runs the QR login (storing the slot credential) and prompts for a Magic-Builder token. See Providers for the alternative that needs no token.
Upgrade from 0.10.0
Section titled “Upgrade from 0.10.0”Install this release and run agent-presence setup. This installs the pinned runtime and rewrites the shim. The hook commands already installed in agents are unchanged, so no uninstall or additional hook re-trust cycle is needed. dsh and the macOS power watcher also call the shim after setup.
Upgrade from 0.9.0 or earlier
Section titled “Upgrade from 0.9.0 or earlier”First run that release’s own uninstall. Its matcher also covers the hook commands of earlier releases, so it removes those installations too, and it keeps credentials, configuration and state. If its setup ran with install-target variables such as CLAUDE_SETTINGS_FILE, keep them set for the uninstall:
npx --yes @rivus/agent-presence@0.9.0 uninstallFor a checkout installation, run node <checkout>/dist/src/cli.js uninstall instead, before updating that checkout. Remove two kinds of absolute-mode hook entry by hand, because the old uninstall misses them and doctor cannot see them without a presence marker: one whose checkout path needed shell quoting (spaces, non-ASCII, +, ~, …), and one from an AGENT_PRESENCE_CLI_PATH that does not end in dist/src/cli.js. Then install this release and run agent-presence setup. This version’s uninstall removes only the agent artifacts in its harness ledger, so it cannot replace that step. If you skip it:
- Claude Code, Codex, Gemini CLI and Grok run both versions’ hooks for each event; Grok also reads
~/.claude/settings.json, so it runs the old--source claudehook.agent-presence doctorreports these duplicates, listinggroknext toclaude-code, except an old command that runs a checkout by absolute path, which carries no presence marker. Run the 0.9.0 uninstall, then runagent-presence setupagain: the old uninstall deletes~/.config/opencode/plugins/agent-presence.js, the path where this version also installs its opencode bridge. - Both versions install the opencode and Pi bridges at the same paths, so setup reports each old bridge as an
unmanaged-existsconflict with the choicesadoptandbackup, andsetup --yesstops there. Cancel, run the 0.9.0 uninstall, then run setup again. Do not chooseadoptorbackup:adoptgoes on without the old uninstall, so the old Claude Code, Codex and Gemini CLI hooks and the oldopencode.jsonplugin entry stay, andbackupis worse, because it keeps the old bridge as the file a lateragent-presence uninstallrestores, which brings the old hook back. If you chosebackupearlier, running the old uninstall and setup does not clear that saved file, so delete the restored~/.config/opencode/plugins/agent-presence.jsand~/.pi/agent/extensions/agent-presence.tsby hand after runningagent-presence uninstall.doctordoes not inspect bridges.
The old uninstall also removes any Claude, Codex or Gemini hook containing dist/src/cli.js hook, including another tool’s hook; save and restore those unrelated entries if needed. It removes the dsh plugin and macOS watcher too; setup offers dsh again and reinstalls the watcher. Moving Codex to the stable shim’s hook --agent command is expected to require one hook re-trust cycle. Later upgrades that only replace the shim keep its installed hook definition stable.
Downgrade to 0.9.0 or earlier
Section titled “Downgrade to 0.9.0 or earlier”Downgrade in this order:
agent-presence uninstall— removes the artifacts the harness ledger records and reports anything it kept.- Move or remove everything the uninstall report lists as kept.
agent-presence doctor— remove by hand any leftover new artifacts or entries overlapping the old locations that it reports.agent-presence worker --stop— applies pending queued events, then stops this version’s hooks and worker from recording again.- Install the old release and run its
agent-presence setup. Each event must fire exactly once.
The harness ledger lives under $XDG_STATE_HOME/agent-kit/harness (default ~/.local/state/agent-kit/harness); deleting it is not a downgrade step. Do not run the old setup first: it adds a second command hook beside the kit registration, overwrites the ledgered opencode bridge without updating the ledger, and the old Pi installer refuses the kit bridge, leaving a partial installation.
Installed locations
Section titled “Installed locations”These are the default user locations for selected agents. The plan shows the resolved paths when an agent home is overridden.
| Agent | Managed artifact |
|---|---|
| Claude Code | Plugin at ~/.claude/skills/agent-presence/, with .claude-plugin/plugin.json and hooks/hooks.json; setup does not add hooks to ~/.claude/settings.json. |
| Codex | With the codex CLI available, a marketplace/plugin at ~/.codex/plugins/agent-presence/, registered through codex plugin in ~/.codex/config.toml; Codex runs its installed cache copy. Without that CLI, hook groups are written to ~/.codex/config.toml. |
| Gemini CLI | Extension at ~/.gemini/extensions/agent-presence/, with gemini-extension.json and hooks/hooks.json. |
| Grok | Its own hook file, ~/.grok/hooks/agent-presence.json. |
| opencode | Bridge at ~/.config/opencode/plugins/agent-presence.js. |
| Pi | Bridge at ~/.pi/agent/extensions/agent-presence.ts, discovered from the extension directory. |
The dsh plugin and macOS power watcher remain presence-managed steps outside the harness bundle. Setup recognizes an already-installed presence dsh plugin by its marker and automatically rewrites it to call the shim, without asking. This also happens with --yes or in a non-interactive terminal; it does not depend on accepting a fresh-install prompt. Only a fresh dsh plugin installation requires confirmation, and setup offers it only when dsh is detected in an interactive terminal. The plugin lives at ~/.dsh/plugins/agent-presence.mjs and is registered in ~/.dsh/cordis.patch.yml. If setup cannot read the plugin to inspect its marker, it prints one note, skips dsh work and continues provider setup and runtime pruning. --no-hooks neither inspects nor rewrites the plugin.
All harness hooks, the dsh plugin and the macOS power watcher call ~/.agent-presence/bin/agent-presence. Setup atomically replaces this shim. It uses the Node executable from setup, falling back to node on PATH if that file disappears. In the default package mode, the CLI is ~/.agent-presence/runtime/<version>/node_modules/@rivus/agent-presence/dist/src/cli.js; absolute mode uses the checkout’s CLI. The agent hook command stays the same in both modes. Absolute mode needs the checkout to remain available.
Setup reuses a runtime whose package version matches and whose CLI exists. After successful setup, cleanup runs under the runtime lock. It keeps this setup’s version, the runtime selected by the previous shim before rewriting, and the runtime selected by the shim at cleanup time. This preserves the previous worker’s files and the runtime selected by an overlapping setup that finished earlier. It removes only other version directories and leftover runtime/.install-* installation directories; directories with other names are preserved. The standalone checkout scripts install:dsh-plugin and install:shutdown-watcher keep an existing shim or create an absolute-mode shim when none exists.
For command hooks, Claude Code, Codex and Grok receive timeout: 5 in seconds, while Gemini receives timeout: 5000 in milliseconds. The opencode/Pi bridges use a 5000 ms child-process timeout only for synchronous finish delivery; other events are sent asynchronously without a child-process timeout. Gemini uses SessionStart, BeforeAgent, BeforeTool, AfterTool, AfterAgent and SessionEnd. Claude’s plugin placement avoids adding presence hooks to the settings file Cursor also reads; presence does not install a Cursor source.
Switching existing Codex registrations to the shim’s hook --agent command is expected to require one hook re-trust cycle. Review the prompts listed in the plan and approve through Codex; setup does not alter trust state. Later updates that only replace the shim keep the installed hook definition stable. The real-agent checks on the 0.11.0 release ran fresh installs in isolated temporary homes and did not exercise that migration re-trust: Claude Code 2.1.301 loaded the installed plugin and fired its hooks; Codex 0.162.1 asked one launch-time review, ran the hooks after approval, and asked for no new review after a setup rerun with no changes; Gemini CLI 0.64.0 loaded the extension; Cursor CLI 2026.10.16 ran tool calls without running presence’s hooks. Older Gemini CLI versions and the Cursor desktop app are untested.
Inspect and remove
Section titled “Inspect and remove”agent-presence doctoragent-presence inventoryagent-presence uninstalldoctor checks hook health and the harness ledger for all six supported agents, even if they are no longer detected; warnings and errors produce a non-zero exit. Its duplicate checks use both the presence-specific markers of releases before 0.10.0 and the installed command, and cover command-hook files, not opencode/Pi bridge files. It also checks other tools’ hooks, so their warnings can cause exit 1. inventory shows the shared kit ledger, including other applications’ entries. Both commands accept --json; see Commands for their limits.
uninstall covers all six supported agents, including agents no longer detected. It reports removed artifacts and every kept location with its reason, then independently removes the shim, the whole ~/.agent-presence/runtime/ directory, dsh plugin and macOS watcher. It preserves credentials, configuration and session state by default. It removes only harness-recorded agent artifacts; hooks installed by 0.9.0 or earlier are not in that ledger, so remove them with that release’s uninstall as described above.