Ingest Hooks CLI

agent session event -> tool hook -> provon ingest trace <source> <hook> -> OTLP -> POST /v1/traces

The hook command hands the payload to a detached reporter and returns immediately, so it does not block the agent or trip a hook timeout.

Supported Tools#

Installation is idempotent: re-running ingest hooks install updates existing entries rather than duplicating them. Provon-owned entries are replaced; entries owned by other tools are left untouched.

Current Live-Capture Status#

The baked command differs by tool; not every target uploads in this build:

• Claude, Codex, Cursor — hook files invoke provon ingest trace <source> <hook>, the runtime entry this CLI registers. Live capture works.
• OpenCode, dsh, Pi — the generated plugin currently execs provon trace <source> <hook> without the ingest segment. This build has no top-level trace command, so these three targets do not upload traces today.

Workarounds in this build:

• Pi persists sessions under ~/.pi/agent/sessions, which ingest sync scans:

  bashCopy

  provon ingest sync ~/.pi/agent/sessions --once

• OpenCode and dsh do not persist transcripts into a directory that ingest sync scans, so there is no CLI backfill path for them in this build. Prefer Claude, Codex, or Cursor for live capture until the plugin invocation is aligned to provon ingest trace.

Prerequisites#

1. Resolve credentials before install. Hooks install reads the --project / --api-key flags or the active profile; it does not read PROVON_API_KEY / PROVON_PROJECT_ID from the environment:

   bashCopy

   provon auth login
   # or
   provon auth token set --api-key "$PROVON_API_KEY" --project "$PROVON_PROJECT_ID"
   # or pass flags directly:
   provon --project <project-id> --api-key <key> ingest hooks install

2. The provon binary must be resolvable by the agent shell; the installer records the command path at install time.

Install#

Install hooks for every detected tool:

provon ingest hooks install

The command auto-detects targets from config directories or commands on PATH; skipped tools are listed in the output with the reason.

Install for a single tool or a subset:

provon ingest hooks install --claude
provon ingest hooks install --codex --cursor

Force installation when detection misses a tool:

provon ingest hooks install --pi --skip-check

Project-Level vs Global#

By default hooks are written to the user's global config and apply to every project. To install only for a specific project:

provon ingest hooks install --project-dir /path/to/project

This writes to <project-dir>/.claude/settings.json, <project-dir>/.cursor/hooks.json, and similar project-level files. dsh has no project-level config and is skipped when --project-dir is set.

Install Options#

| Option | Purpose | | --------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------- | | --project-dir <path> | Install into project-level directories instead of global config | | --claude / --codex / --opencode / --dsh / --cursor / --pi | Limit install to the listed targets | | --skip-check | Skip tool detection and write to all selected targets | | --mode <mode> | Recording mode: coding, coding_write, in_repo, all (default all) | | --report-level <level> | full (default) or summary | | --disable <0 | 1> | Install entries switched off; default 0 | | --append | Add an additional reporting target instead of replacing the existing one | | --repo <slug> | Record a repository selector (repeatable) | | --path <dir> | Record a directory selector (repeatable) | | --skill <name> / --skill-keyword <kw> | Record skill selectors (repeatable) | | --mcp <name> | Record an MCP selector (repeatable) | | --keyword <kw> / --cli <name> | Record content/command selectors (repeatable) |

The selectors above are stored inside the baked PROVON_TRACE_CONFIG target record for use by downstream processing; treat them as recorded metadata rather than a guaranteed runtime filter in the current build.

Multiple Reporting Targets#

By default, installing for a project replaces the existing reporting target in the same hooks file. Append an additional target instead:

provon --project <second-project> --api-key <second-key> ingest hooks install --append

If another tool already reports to the same project in the same file, installation aborts with TARGET_CONFLICT to prevent double reporting. --append also aborts (APPEND_CONFLICT) when the target already owns a reporting entry.

Uninstall#

Remove Provon entries from every tool:

provon ingest hooks uninstall

Limit removal to specific tools:

provon ingest hooks uninstall --claude --codex

Only Provon-owned entries are removed; other tools' hooks and unrelated config keys are preserved. For Codex, trust-state entries in config.toml are also cleared.

Runtime Environment Variables#

Success Check#

1. Install output lists installed targets and an empty skipped list for the tools you expect.

2. Run one agent turn in a supported tool, then open the project Traces view; a new conversation appears after the tool's hook fires.

3. Manual sanity check with debug logging:

   bashCopy

   echo '{"transcript_path":"/path/to/session.jsonl"}' \
     | PROVON_TRACE_DEBUG=1 PROVON_TRACE_SYNC=1 \
       provon ingest trace claude stop

Troubleshooting#