@groundtrack/hooks
Set up Groundtrack across Claude Code, Codex, Cursor, and OpenCode in one flow. Node.js 18 or newer is required.
npx --yes --package @groundtrack/hooks@latest groundtrack setup
Choose the agents you use, review the changes, and finish any sign-in or hook approval shown for each agent. The picker detects both machine installations and project configuration. Your choices are remembered; adding Codex later preserves your working Claude and Cursor connections.
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 is repeatable. --client and claude-code are accepted aliases.
Setup configures the current project; it does not activate Groundtrack in every
repository. Use --repo PATH to choose a project and --url URL for another
Groundtrack endpoint. With no explicit targets, an interactive terminal shows
the picker. An unattended --yes run needs a previously saved selection or
explicit --agent / --all-detected; it never falls back to all known agents.
An empty selection or cancellation makes no changes.
The same package provides groundtrack-hook. Setup installs this shared runtime
once if needed for Claude, Codex, or Cursor. OpenCode uses
@groundtrack/opencode-plugin instead. Repeat runs use the installed runtime
without querying npm for updates on every invocation.
The CLI validates JSON/JSONC and TOML, preserves unrelated settings and comments,
reuses existing Groundtrack aliases, and backs up changed files before applying
atomic writes. Backups and selections live under
$XDG_CONFIG_HOME/groundtrack (default ~/.config/groundtrack). Backups may
contain existing private configuration, so their directory and files are private.
A failure rolls back completed writes where possible and reports the backup
location. Malformed configuration, symbolic links, disabled connections/hooks,
and endpoint conflicts are reported for the affected agent. Other independent
selected agents can still be configured. Adding agents does not uninstall others.
Connection and verification
A local check verifies configuration, not a live authenticated host. Status
reports configured and activation: unverified; it never infers a connection
from a generated file. Each agent must load the connection and its hooks.
Interactive setup checks native sign-in requirements first. Claude Code must
approve a new project MCP server before OAuth; setup shows that action instead
of attempting a login that will fail. Codex can authenticate the selected endpoint
with a one-command configuration override while project and hook trust remain
explicit user actions. Existing Claude/OpenCode authentication is reused when
the client reports it, and successful logins are reflected in the final summary.
Use --connect to retry native sign-in for selected clients. Cursor and
desktop-only installations show their UI steps. In unattended runs, setup prints instructions and never blocks waiting
for OAuth. --json returns structured results without configuration contents or
credentials; use --yes to apply an explicitly selected setup.
Codex requires review and trust of the Groundtrack hook through /hooks or its
hook approval UI. New Codex setups use .codex/hooks.json; existing inline
hooks in .codex/config.toml are recognized and repaired without duplicating
them. Claude's CLAUDE.md imports the shared AGENTS.md policy. The plugin is
added to the existing OpenCode JSON/JSONC configuration.
Claude setup also installs a synchronous SessionStart check in project settings.
At startup, resume, clear, or fork it checks local MCP configuration and Claude's
own mcp get status. If Groundtrack is missing, disabled, awaiting approval,
unauthenticated, or not connected, Claude shows a warning with a repair command
and gives the agent the same context. An incomplete OAuth flow can leave Claude
in Needs authentication even when mcp get exits successfully; this state is
not treated as connected. The check never starts OAuth or blocks the session on
failure; its native probe has a five-second limit. It needs Claude project hooks
to be enabled and trusted, and is not a replacement for a live tool call. Other
clients still rely on their own setup and diagnostics.
In each selected agent, ask:
Verify Groundtrack's connection and hook context with search_experiences.
The returned hook-context and instruction-version warnings determine whether live activation needs attention. No synthetic engineering event is required.
Doctor compatibility
groundtrack doctor is an alias for status; groundtrack doctor --fix uses the
same setup and repair flow. Doctor checks for a newer published hooks package;
when one is available, upgrade before repairing with an older bundled policy.
If the registry is unavailable, Doctor still checks local configuration and
preserves managed instructions newer than its own template. When invoked through
npx, Doctor checks the globally installed hook runtime rather than the
temporary executable provided by npx. Existing single-client commands continue to work:
groundtrack doctor --fix --client codex
The lower-level runDoctor API remains for existing consumers. New setup uses
client-specific plans for MCP, hooks/plugins, and instructions, so it can preview
and repair several selected agents safely.
Local impact skill (opt-in)
The package includes a read-only groundtrack-impact skill for Claude Code and
Codex. It audits local sessions to produce an evidence-backed report on how
Groundtrack changed your work. Setup does not install or invoke this skill;
install it explicitly only when you want to give an agent access to local
transcripts. From this repository checkout, choose either or both agents:
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/"
If @groundtrack/hooks is installed in another project, use
node_modules/@groundtrack/hooks/skills/groundtrack-impact as the copy source
instead. For Claude Code, set this copied skill to user-only in /skills
(or set "groundtrack-impact": "user-invocable-only" under skillOverrides in
Claude settings) before using it; that prevents Claude from loading this
transcript-reading workflow on its own. Codex's packaged agents/openai.yaml already
disables implicit invocation. Restart your agent if needed, then explicitly invoke
$groundtrack-impact in Codex or /groundtrack-impact in Claude Code and
authorize the session scope. The audit reads Claude
sessions from CLAUDE_CONFIG_DIR (default ~/.claude) and Codex sessions from
CODEX_HOME (default ~/.codex); it never uploads transcripts or runs the
session-import command. The agent's model provider may receive selected local
context during analysis.
Import coding-agent sessions
Import completed Codex, Claude Code, Cursor, or OpenCode sessions with an API key created in Groundtrack
Settings. The default scope is the current Git repository; subagents and files modified
in the last five minutes are excluded. Groundtrack reads Codex sessions from CODEX_HOME
(default ~/.codex), Claude sessions from CLAUDE_CONFIG_DIR (default ~/.claude),
and Cursor transcripts from CURSOR_HOME (default ~/.cursor). Cursor metadata comes from
its local state.vscdb; set CURSOR_STATE_DB to override that database path. Cursor import
is CLI-only and requires unflagged node:sqlite support (Node.js 22.13+, 23.4+, or 24+).
OpenCode import invokes the installed opencode CLI (override it with OPENCODE_BIN) and uses
private temporary files for its session inventory and exports. This avoids OpenCode's large piped
export truncation while ensuring the unsanitized source export is removed after local pruning.
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
The command streams source files through a deterministic privacy filter before upload.
Reasoning, system/developer instructions, turn context other than the model name, and
recognized credentials are removed locally. Uploads are sequential and retry only
transient failures. Successful imports are recorded atomically under
$XDG_CONFIG_HOME/groundtrack; receipts are scoped to the endpoint, API-key fingerprint,
visibility, source hash, and canonicalization version. Use --json for one machine-readable
result object and --url for a preview or self-hosted deployment.
Imported transcripts are private by default. Groundtrack analyzes completed imports and may add high-confidence extracted lessons—not transcript content—to the organization's shared knowledge. Changing transcript visibility does not change this learning behavior; deleting an imported session retracts its derived knowledge.
Watch completed sessions
groundtrack watch --once is the sync engine behind a future scheduled watcher.
One pass scans session file metadata, compares it with a durable cursor, and only
reads and uploads files whose size or modification time changed. Files modified in
the last five minutes stay active; once they are quiet, the pass prunes and
uploads them using the same privacy filter and receipts as 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
The cursor lives at $XDG_CONFIG_HOME/groundtrack/watch-state-<source>.json (mode
0600). Unchanged files are not reopened, rehashed, or re-uploaded. A preview
without --yes does not write cursor state. Only one watch pass can run per source
at a time; a stale PID lock is recovered automatically. The loop, filesystem
events, and an OS timer are intentionally not part of --once.
Codex paginated sessions are merged before upload. The watcher groups rollout
pages by session_id, follows the history_base.thread_id chain, and uploads one
complete snapshot. A chain with a missing or still-live page is reported instead
of uploading a fragment.
templates/AGENTS.md is the source of truth for the managed repository policy.
After changing it, run pnpm sync:agent-instructions; tests reject drift between
the setup guide, this repository's managed AGENTS.md block, and the packaged template.
Development
Agent IDs, names, aliases, event sources, enrichment kinds, and session-import
capabilities are defined once in src/agents.ts, exported as
@groundtrack/hooks/agents. The CLI, web UI, hooks, and server consume that
catalog and its derived types. Keep it dependency-free so browser bundles can
load it without the Node-only hook runtime.
Build and test the CLI from the repository:
pnpm --filter @groundtrack/hooks build
node packages/hooks/dist/groundtrack.js setup --repo /path/to/test-project
pnpm --filter @groundtrack/hooks test
With Claude Code and Codex installed, also run the isolated native-client preflight checks (they do not start OAuth or touch your normal agent profiles):
GROUNDTRACK_TEST_NATIVE_CLIENTS=1 pnpm --filter @groundtrack/hooks test
The groundtrack-hook command reads a pre-tool-use hook payload from standard input and enriches
Groundtrack store_event and search_experiences calls with:
- the client session and model identifiers (using Claude's host-provided transcript path when its hook payload omits the model);
- for
store_event, a stable client event id derived from the host's tool invocation id; and - repository, branch, commit, and dirty-worktree context collected with Git.
The Git context is collected from the hook's working directory (or a single Cursor workspace root) and overrides model-provided values. Collection fails open when the hook is outside a Git worktree. The command does not send network requests.
Update it with:
npm update -g @groundtrack/hooks