@groundtrack /钩子
在一个流程中设置跨Claude Code， Codex， Cursor和OpenCode的Groundtrack。 需要Node.js 18或更新版本。
npx --yes --package @groundtrack/hooks@latest groundtrack setup
选择您使用的代理，检查更改，并完成任何登录或挂钩 每种代理的批准。拾取器检测两个机器安装 以及项目配置。你的选择会被记住；后来添加法典 保留您的工作克劳德和光标连接。
groundtrack setup --agent codex
groundtrack setup --agent claude --agent codex --agent cursor --yes
groundtrack setup --all-detected --yes
groundtrack setup --agent codex --dry-run
groundtrack status
groundtrack status --json
--agent 是可重复的。 --client 和 claude-code 是可接受的别名。
安装程序配置当前项目；它不会在每个地方激活Groundtrack
存储库。使用 --repo PATH 选择一个项目和 --url URL 为另一个
Groundtrack端点。没有明确的目标，交互式终端显示
选择器。一个无人值守 --yes 运行需要先前保存的选择或
显式的 --agent / --all-detected;它永远不会落在所有已知的特工身上。
空的选择或取消不会产生任何更改。
相同的包提供 groundtrack-hook． 安装程序安装这个共享运行时
一次，如果需要，为克劳德，法典，或光标。OpenCode使用
@groundtrack/opencode-plugin 代替。重复运行使用已安装的运行时
无需查询NPM以获取每次调用的更新。
CLI验证JSON/JSONC和TOML，保留不相关的设置和注释，
重用现有的Groundtrack别名，并在应用前备份更改的文件
原子写道。备份和选择位于
$XDG_CONFIG_HOME/groundtrack (默认 ~/.config/groundtrack）. 备份可能
包含现有的私有配置，因此它们的目录和文件是私有的。
故障回滚完成的写入，并报告备份
的位置。错误的配置，符号链接，禁用的连接/钩子，
并且报告受影响代理的端点冲突。其他独立
仍然可以配置所选的代理。添加代理不会卸载其他代理。
连接与验证
本地检查验证配置，而不是活动的经过身份验证的主机。状态
报告 configured 和 activation: unverified;它从不推断出一种联系
从生成的文件。每个代理都必须加载连接及其钩子。
交互式设置首先检查本机登录需求。克劳德代码必须
在OAuth之前批准一个新的项目MCP服务器；安装程序将显示该操作
尝试登录失败。Codex可以对选定的端点进行身份验证
在项目和钩子信任保持不变的情况下，使用一个命令的配置重写
明确的用户操作。现有的Claude/OpenCode身份验证被重用
客户端报告它，成功的登录将反映在最终的摘要中。
使用 --connect 为选定的客户端重试本机登录。光标,
仅桌面安装将显示其UI步骤。在无人值守的运行中，setup打印指令并且从不阻塞等待
OAuth。 --json 返回没有配置内容的结构化结果
凭证;使用 --yes 应用显式选择的安装程序。
法典要求审查和信任Groundtrack钩通过 /hooks 或其
钩子审批UI。新的法典设置使用 .codex/hooks.json;现有的内联
钩子在 .codex/config.toml 被识别和修复，没有复制
他们。克劳德的 CLAUDE.md 导入共享 AGENTS.md 策略。插件是
添加到现有的OpenCode JSON/JSONC配置。
克劳德安装还安装了一个同步 SessionStart 签入项目设置。
在启动、恢复、清除或fork时，它会检查本地MCP配置和Claude的配置
自己的 mcp get 的地位。如果Groundtrack丢失，残废，等待批准，
未经身份验证或未连接时，Claude显示一个带有修复命令的警告
并给予agent相同的上下文。不完整的OAuth流可能会离开Claude
在 Needs authentication 即使 mcp get 成功退出;这个状态是
不被视为有联系。检查从不启动OAuth或阻止会话
失败;它的原生探测器有5秒的限制。它需要克劳德项目钩子
启用和信任，而不是实时工具调用的替代品。其他
客户端仍然依赖自己的设置和诊断。
在每个选定的代理中，询问：
用search_experiences验证Groundtrack的连接和钩子上下文。
返回的钩子上下文和指令版本警告决定是否 实时激活需要注意。不需要合成工程事件。
医生的兼容性
groundtrack doctor 的别名 status； groundtrack doctor --fix 使用
相同的安装和维修流程。医生检查新发布的钩子包；
如果有可用的策略，请在使用较旧的捆绑策略进行修复之前进行升级。
如果注册表不可用，医生仍然检查本地配置和
保留比自己的模板更新的托管指令。通过调用时
npx， Doctor检查全局安装的钩子运行时，而不是
提供的临时可执行文件 npx． 现有的单客户端命令继续工作：
groundtrack doctor --fix --client codex
较低级别 runDoctor API仍然为现有的消费者服务。新设置使用
客户特定的MCP计划，钩子/插件，和指令，所以它可以预览
并安全修复几种选定的代理商。
本地影响力技能（可选择加入）
该包包含一个只读的 groundtrack-impact 技能克劳德代码和
法典。它对地方会议进行审计，并就如何进行审查提出一份有证据支持的报告
跑道改变了你的工作。 安装程序不安装或调用此技能；
只有当您希望为代理提供对local的访问权限时，才显式地安装它
记录。从这个存储库签出，选择一个代理或两个代理：
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R packages/hooks/skills/groundtrack-impact "${CODEX_HOME:-$HOME/.codex}/skills/"
mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills"
cp -R packages/hooks/skills/groundtrack-impact "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/"
如果 @groundtrack/hooks 安装在另一个项目中，使用
node_modules/@groundtrack/hooks/skills/groundtrack-impact 作为复制源
代替。对于Claude Code，将此复制技能设置为 用户只 在 /skills
(或一组 "groundtrack-impact": "user-invocable-only" 下 skillOverrides 在
克劳德设置)使用前；阻止克劳德把这个装上
自己的转录阅读工作流程。食品的包装 agents/openai.yaml 已经
禁用隐式调用。如果需要，重新启动代理，然后显式调用
$groundtrack-impact 法典或 /groundtrack-impact 在克劳德法典中
授权会话范围。审计显示克劳德
会议从 CLAUDE_CONFIG_DIR (默认 ~/.claude)和法典会议
CODEX_HOME (默认 ~/.codex）; 它从不上传成绩单，也不会运行
session-import命令。代理的模型提供者可以接收选定的本地
分析过程中的上下文。
导入编码代理会话
使用在Groundtrack中创建的API密钥导入完成的Codex、Claude Code、Cursor或OpenCode会话
设置。默认作用域是当前Git存储库；修改子代理和文件
在最后五分钟内被排除在外。Groundtrack读取Codex会议 CODEX_HOME
(默认 ~/.codex)， Claude sessions从 CLAUDE_CONFIG_DIR (默认 ~/.claude)，
和游标转录本 CURSOR_HOME (默认 ~/.cursor）. 游标元数据来自
其本地 state.vscdb;集 CURSOR_STATE_DB 以覆盖该数据库路径。光标进口
仅限cli并且需要未标记 node:sqlite 支持（Node.js 22.13+， 23.4+或24+）。
OpenCode导入调用已安装的 opencode CLI(用 OPENCODE_BIN)及用途
用于会话目录和导出的私有临时文件。这避免了OpenCode的大型管道
导出截断，同时确保在本地修剪后删除未消毒的源导出。
GROUNDTRACK_API_KEY=... groundtrack import --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --yes
GROUNDTRACK_API_KEY=... groundtrack import --agent claude --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --agent claude --all-repos --yes
GROUNDTRACK_API_KEY=... groundtrack import --agent cursor --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --agent cursor --all-repos --yes
GROUNDTRACK_API_KEY=... groundtrack import --agent opencode --dry-run
GROUNDTRACK_API_KEY=... groundtrack import --agent opencode --all-repos --yes
该命令在上传前通过确定性隐私过滤器对源文件进行流处理。
推理，系统/开发人员指令，转换上下文而不是模型名称，以及
在本地删除已识别的凭据。上传是顺序的，只能重试
瞬态故障。成功的导入自动记录在
$XDG_CONFIG_HOME/groundtrack;收据的范围限定在端点，api密钥指纹，
可见性、源散列和规范化版本。使用 --json 对于一个机器可读的
结果对象和 --url 用于预览或自托管部署。
默认情况下，导入的脚本是私有的。Groundtrack分析已完成的导入，并可能添加 高可信度提取的经验教训——而不是抄写的内容——是组织的共享知识。 改变成绩单可见性并不能改变这种学习行为；删除导入的 会话收回其派生的知识。
观察完成的会话
groundtrack watch --once 是未来预定的监视器背后的同步引擎。
一次遍历扫描会话文件元数据，并将其与持久游标进行比较
读取和上传大小或修改时间发生变化的文件。中修改的文件
最后五分钟 active;一旦他们安静下来，就把西梅和
使用相同的隐私过滤器和收据上传 import.
GROUNDTRACK_API_KEY=... groundtrack watch --once --agent codex --dry-run
GROUNDTRACK_API_KEY=... groundtrack watch --once --agent codex --all-repos --yes
GROUNDTRACK_API_KEY=... groundtrack watch --once --agent claude --all-repos --yes
游标位于 $XDG_CONFIG_HOME/groundtrack/watch-state-<source>.json (模式
0600）. 未更改的文件不会重新打开、重新散列或重新上传。一个预览
没有 --yes 不写入游标状态。每个源只能运行一个watch pass
一次；失效的PID锁自动恢复。循环、文件系统
事件和操作系统计时器故意不属于 --once.
Codex分页会话在上传之前被合并。观察员小组开始行动
页面 session_id，紧跟着 history_base.thread_id 链接，并上传一个
完整的快照。相反，报告一个丢失或仍然存在的页面的链
上传一个片段。
templates/AGENTS.md 是托管存储库策略的事实来源。
修改完成后，运行 pnpm sync:agent-instructions;测试拒绝两者之间的漂移
安装指南，这个存储库是托管的 AGENTS.md 块，以及打包后的模板。
开发
Agent id、名称、别名、事件源、富集类型、会话导入
功能是一次性定义的 src/agents.ts，出口为
@groundtrack/hooks/agents． 命令行、web UI、钩子和服务器都要使用它
目录及其派生类型。保持它不依赖，这样浏览器包就可以
在没有Node-only钩子运行时的情况下加载它。
从存储库构建并测试CLI：
pnpm --filter @groundtrack/hooks build
node packages/hooks/dist/groundtrack.js setup --repo /path/to/test-project
pnpm --filter @groundtrack/hooks test
安装了Claude Code和Codex后，还要运行隔离的本机客户端 飞行前检查（他们不启动OAuth或触摸您的正常代理配置文件）：
GROUNDTRACK_TEST_NATIVE_CLIENTS=1 pnpm --filter @groundtrack/hooks test
这个 groundtrack-hook 命令从标准输入读取工具使用前的钩子负载并进行充实
Groundtrack store_event 和 search_experiences 电话:
- 客户端会话和模型标识符（使用Claude的主机提供的） 当钩子有效载荷忽略模型时，脚本路径)；
- 用于
store_event，从主机的工具调用id派生的稳定客户端事件id；和 - Git收集的存储库、分支、提交和脏工作树上下文。
Git上下文从钩子的工作目录（或单个目录）中收集 游标工作区根)并覆盖模型提供的值。收藏失败 当钩子在Git工作树之外时打开。该命令不发送网络 请求。
更新它：
npm update -g @groundtrack/hooks