安装
agent-presence 运行于 macOS 和 Linux(不支持 Windows),需要 Node.js 22.13 或更高版本。凭据保存在 macOS 的 Keychain、Linux 的 libsecret 中。
已使用 0.9.0 或更早版本的用户,请先按升级指引操作,再替换安装的包。
pnpm add -g @rivus/agent-presenceagent-presence setupnpm i -g @rivus/agent-presenceagent-presence setupbun add -g @rivus/agent-presenceagent-presence setupsetup 检测六个受支持的智能体:claude-code、codex、gemini-cli、grok、opencode 和 pi,选择状态为 found 或 runnable 的智能体。检测只检查 PATH 中的命令,或智能体自身的会话、状态存储和凭据文件是否存在,不运行智能体命令,也不读取凭据内容,因此仅凭检测不能确认 runnable。
智能体自身的默认检测路径如下:
| 智能体 | 检测路径 |
|---|---|
| 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 和 PI_CODING_AGENT_DIR 会替换对应的默认 home。GEMINI_CLI_HOME 替换 Gemini 的父目录,因此检测路径位于 $GEMINI_CLI_HOME/.gemini/ 下。设置 XDG_DATA_HOME 时,opencode 使用 $XDG_DATA_HOME/opencode/;检测检查数据目录,不检查插件或配置目录。
空会话存储也算证据;即使可执行文件已被移除,保留的智能体自身状态仍可使结果为 found。智能体 home 目录本身、presence hook 或插件、共享 settings、MCP 配置都不算证据,因此运行 presence setup 不会让原本缺失的智能体变为可检测。
未找到智能体时,setup 会提示先安装它,再运行 setup。如果某项检查未能完成,且没有其他证据能确认智能体存在,setup 将其记为 unknown 并跳过,列出失败的检查并提示使用 --agents。仅安装桌面应用、从未运行 CLI 且命令不在 PATH 中时,需要此参数。也可用它限制安装范围。参数接收逗号分隔的受支持 kit id:
agent-presence setup --agents claude-code,codex未知 id 和 presence 不支持的 kit id 都会报错。未被检测选中或未列入 --agents 的智能体,其 hook 保持不变。只有 harness 安装记录中存在属于 agent-presence 的未选中智能体条目时,setup 才会列出这些智能体,并提示用 agent-presence setup --agents <id,...> 更新它们。agent-presence uninstall 会移除所有智能体的 presence hook。以后安装智能体后,重新运行 setup 即可添加 hook。没有检测到智能体且未传 --agents 时,setup 跳过智能体安装计划、确认、应用和校验,但仍按所选 --hook-command 模式准备 shim:package 安装或复用固定版本 runtime,absolute 使用 checkout 的 CLI。准备成功后才继续 watcher、dsh 和 provider 步骤。
setup 先列出配置冲突和允许的处理方式,按你的选择重新规划,再展示完整变更、命令和预期信任提示。确认计划后才会写入智能体配置。取消、拒绝确认或遇到受保护目标时,setup 会退出。登录可能已经写入自己的数据。
非交互终端可用 setup --yes 应用无冲突的计划,但它不会自动处理冲突。交互终端始终会请求明确确认,包括传了 --yes 时。确认后,setup 在 package 模式下安装或复用固定版本的 runtime,再写入 shim、应用计划并立即验证本次选中的 kit 产物。runtime 安装失败时,会清理临时安装目录、丢弃计划,并在写入 shim 或任何智能体目标前以非零状态退出。验证失败时,setup 就此停止,不安装 watcher、不询问 dsh、不发布 provider,也不显示签名 URL。验证成功或没有选中智能体时,依次安装 macOS 电源 watcher、更新已有 presence dsh 插件或询问是否首次安装,再配置 provider。取消 dsh 提示或 provider 失败不会跳过验证结果。Linux 跳过 watcher,依靠 TTL 清理。
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 是默认模式:setup 用 npm 将自身的固定发布版本安装到 ~/.agent-presence/runtime/<version>/,随后 hook 直接用 Node 运行已安装的 CLI。只有 setup 安装缺失或损坏的 runtime 时需要 npm 和 https://registry.npmjs.org 访问;hook 执行不调用 npm 或 npx。--hook-command npx 保留为 package 的别名。
若要使用本地 checkout 的构建产物,不安装 runtime,运行:
node <checkout>/dist/src/cli.js setup --hook-command absolute默认 provider 是 magic-builder,所以首次 setup 会先跑扫码登录(保存 slot 凭据),再提示粘贴一个 Magic-Builder token。无需 token 的备选见 Provider。
从 0.10.0 升级
Section titled “从 0.10.0 升级”安装本版本后运行 agent-presence setup 即可。setup 安装固定版本的 runtime 并重写 shim,智能体中已经安装的 hook 命令保持不变,无需先卸载,也不会增加 hook 重新信任流程。setup 后,dsh 和 macOS 电源 watcher 也通过 shim 调用。
从 0.9.0 或更早版本升级
Section titled “从 0.9.0 或更早版本升级”先运行旧版本自己的卸载命令。它的匹配规则也覆盖更早版本的 hook 命令,因此会一并移除这些安装,并保留凭据、配置和状态。如果旧版 setup 运行时设置了 CLAUDE_SETTINGS_FILE 等安装目标变量,卸载时保持这些变量的原值:
npx --yes @rivus/agent-presence@0.9.0 uninstall从 checkout 安装的用户改为在更新 checkout 前运行 node <checkout>/dist/src/cli.js uninstall。有两类 absolute 模式的 hook 条目需要手动移除,因为旧卸载器漏掉它们,doctor 也因为没有 presence 标记而看不到:checkout 路径需要 shell 引号(含空格、非 ASCII 字符、+、~ 等)的条目,以及 AGENT_PRESENCE_CLI_PATH 不以 dist/src/cli.js 结尾时写入的条目。然后安装本版本,再运行 agent-presence setup。本版本的卸载只移除 harness 安装记录中的智能体产物,不能代替这一步。如果跳过这一步:
- Claude Code、Codex、Gemini CLI 和 Grok 会对每个事件运行新旧两个版本的 hook;Grok 也读取
~/.claude/settings.json,因此会运行旧的--source claudehook。agent-presence doctor会报告这些重复 hook,并在claude-code旁列出grok,但以绝对路径运行 checkout 的旧命令不含 presence 标记,识别不了。此时先运行 0.9.0 的卸载,再重新运行agent-presence setup:旧卸载器会删除~/.config/opencode/plugins/agent-presence.js,本版本的 opencode 桥接文件也安装在这个路径。 - 两个版本的 opencode 和 Pi 桥接文件路径相同,因此 setup 会把每个旧桥接文件报告为
unmanaged-exists冲突,可选adopt和backup;setup --yes会在这里退出。先取消,运行 0.9.0 的卸载,再重新运行 setup。不要选择adopt或backup:adopt会跳过旧卸载,旧的 Claude Code、Codex 和 Gemini CLI hook 以及opencode.json中旧的插件项都会留下;backup更糟,因为它会把旧桥接文件保存为之后agent-presence uninstall要恢复的文件,旧 hook 会因此回来。如果之前选过backup,运行旧卸载和 setup 不会清掉这份保存的文件,因此运行agent-presence uninstall后手动删除恢复出来的~/.config/opencode/plugins/agent-presence.js和~/.pi/agent/extensions/agent-presence.ts。doctor不检查桥接文件。
旧卸载器还会移除 Claude、Codex 或 Gemini 中所有包含 dist/src/cli.js hook 的 hook,包括其他工具的 hook;必要时先保存再恢复这些无关项目。它也会移除 dsh 插件和 macOS watcher;setup 会再次询问 dsh,并重新安装 watcher。Codex 切换到稳定 shim 的 hook --agent 命令预计需要重新信任一次 hook。后续仅替换 shim 的升级保持已安装 hook 的定义稳定。
降级到 0.9.0 或更早版本
Section titled “降级到 0.9.0 或更早版本”按以下顺序降级:
agent-presence uninstall:按 harness 记录移除产物,并报告保留的文件。- 移出或删除卸载报告中列出的保留文件。
agent-presence doctor:按报告手动移除残留的新产物或与旧位置重叠的项目。agent-presence worker --stop:先应用排队中的事件,再阻止本版本的 hook 和 worker 继续记录。- 安装旧版本并运行它的
agent-presence setup。每个事件应恰好触发一次。
harness 记录位于 $XDG_STATE_HOME/agent-kit/harness(默认 ~/.local/state/agent-kit/harness);删除它不是降级手段。不要先运行旧版 setup:它会在 kit 注册旁添加第二条命令式 hook,覆盖记录在案的 opencode 桥接文件而不更新记录,旧 Pi 安装器还会拒绝覆盖 kit 桥接,留下半安装状态。
以下是选中智能体的默认用户目录位置;覆盖智能体 home 时,计划会显示解析后的实际路径。
| 智能体 | 管理的产物 |
|---|---|
| Claude Code | ~/.claude/skills/agent-presence/ 中的插件,含 .claude-plugin/plugin.json 和 hooks/hooks.json;setup 不向 ~/.claude/settings.json 添加 hook。 |
| Codex | codex CLI 可用时,在 ~/.codex/plugins/agent-presence/ 创建 marketplace/plugin,通过 codex plugin 在 ~/.codex/config.toml 中注册;Codex 运行安装到缓存中的副本。CLI 不可用时,hook 分组写入 ~/.codex/config.toml。 |
| Gemini CLI | ~/.gemini/extensions/agent-presence/ 中的扩展,含 gemini-extension.json 和 hooks/hooks.json。 |
| Grok | 独立的 hook 文件 ~/.grok/hooks/agent-presence.json。 |
| opencode | 桥接文件 ~/.config/opencode/plugins/agent-presence.js。 |
| Pi | 桥接文件 ~/.pi/agent/extensions/agent-presence.ts,由扩展目录自动发现。 |
dsh 插件和 macOS 电源 watcher 仍由 presence 自行管理,不属于 harness bundle。setup 通过标记识别已经安装的 presence dsh 插件,自动将其重写为调用 shim,无需询问;传了 --yes 或处于非交互终端时也会更新,不依赖用户接受首次安装提示。只有首次安装 dsh 插件才会请求确认,且仅在交互终端检测到 dsh 时提供安装。插件位于 ~/.dsh/plugins/agent-presence.mjs,注册在 ~/.dsh/cordis.patch.yml。如果无法读取插件来检查标记,setup 只显示一条提示,跳过 dsh 操作,继续 provider 设置和 runtime 清理。--no-hooks 既不检查也不重写该插件。
所有 harness hook、dsh 插件和 macOS 电源 watcher 都调用 ~/.agent-presence/bin/agent-presence。setup 以原子替换方式更新 shim。shim 使用 setup 当时的 Node 可执行文件,该文件消失时回退到 PATH 中的 node。默认 package 模式下,CLI 位于 ~/.agent-presence/runtime/<version>/node_modules/@rivus/agent-presence/dist/src/cli.js;absolute 模式使用 checkout 中的 CLI。两种模式安装到智能体中的 hook 命令相同;绝对路径模式要求 checkout 持续可用。
包版本匹配且 CLI 存在时,setup 复用已有 runtime。setup 成功后,在 runtime 锁内执行清理,保留本次 setup 的版本、重写前旧 shim 指向的版本,以及清理时 shim 正指向的版本。这既保留上一版本 worker 的文件,也保护并行 setup 已切换到的 runtime;仅删除其他版本目录和残留的 runtime/.install-* 安装目录,其他名称的目录会保留。独立的 checkout 脚本 install:dsh-plugin 和 install:shutdown-watcher 保留已有 shim;shim 不存在时创建绝对路径模式的 shim。
命令式 hook 中,Claude Code、Codex 和 Grok 按秒写入 timeout: 5,Gemini 按毫秒写入 timeout: 5000。opencode/Pi 桥接仅对同步结束事件的交付设置 5000 毫秒子进程超时;其他事件异步发送,不设置子进程超时。Gemini 使用 SessionStart、BeforeAgent、BeforeTool、AfterTool、AfterAgent 和 SessionEnd。Claude 插件位置避免向 Cursor 也会读取的 settings 文件添加 presence hook;presence 不安装 Cursor 源。
现有 Codex 注册切换到 shim 的 hook --agent 命令后,预计需要重新信任一次 hook。请查看计划列出的提示,通过 Codex 批准;setup 不会修改信任状态。后续仅替换 shim 时,已安装 hook 的定义保持稳定。0.11.0 版本的真实智能体检查均在隔离临时 home 中全新安装,未覆盖这次迁移的重新信任:Claude Code 2.1.301 加载了安装的插件并触发 hook;Codex 0.162.1 启动时审阅一次,批准后 hook 全部运行,setup 原样重跑后无新的审阅;Gemini CLI 0.64.0 加载了扩展;Cursor CLI 2026.10.16 工具调用正常,未运行 presence 的 hook。更早的 Gemini CLI 版本和 Cursor 桌面应用未经测试。
agent-presence doctoragent-presence inventoryagent-presence uninstalldoctor 检查全部六个受支持智能体的 hook 和 harness 安装记录,包括已无法检测到的智能体;警告或错误会导致非零退出码。重复检查同时使用 0.10.0 之前版本的 presence 专属标记和已安装命令,覆盖命令式 hook 文件,不覆盖 opencode/Pi 桥接文件。它也会检查其他工具的 hook,因此其他工具的警告也可能导致退出码 1。inventory 展示共享的 kit 安装记录,包含其他应用的条目。两个命令都支持 --json,完整限制见命令。
uninstall 覆盖全部六个受支持的智能体,包括已无法检测到的智能体。它报告移除的产物及每个保留位置和原因,再独立移除 shim、整个 ~/.agent-presence/runtime/ 目录、dsh 插件和 macOS watcher。默认保留凭据、配置和 session 状态。智能体产物只按 harness 记录移除;0.9.0 或更早版本安装的 hook 不在该记录中,应按上面的升级步骤用该版本的卸载命令移除。