Skip to content

feat(trace): skip agent hooks when the Chainloop CLI is unavailable #3687

Closed

Description

@migmartri

Claude Code and Cursor hooks invoke chainloop trace hook … directly. If a developer opens a repository with these hooks installed but the Chainloop CLI is absent from PATH, the shell exits with code 127 before Chainloop's best-effort error handling can run.

Git hooks already check command -v chainloop before invoking the CLI. The OpenCode plugin catches process-start failures and lets the agent continue.

Add the same missing-CLI handling to the generated Claude Code and Cursor hook commands: check whether chainloop is available, exit successfully if it is missing, and execute the hook when it is present.

Example Claude Code hook entry:

{
  "hooks": [
    {
      "type": "command",
      "command": "sh -c 'if ! command -v chainloop >/dev/null 2>&1; then exit 0; fi; exec chainloop trace hook claude post-tool-use'"
    }
  ]
}

For Cursor, apply the same guard to its existing chainloop trace hook cursor … commands, keeping the Cursor hook configuration format.

The guard returns success only when the CLI is unavailable. exec forwards stdin and output and preserves the CLI's exit status when it is available.

Acceptance criteria:

  • Missing Chainloop CLI: agent hooks exit successfully without a command-not-found error.
  • CLI available: preserve stdin, JSON stdout, and the hook command's exit status.
  • Existing user hooks remain unchanged; installation remains idempotent.
  • Re-running chainloop trace init updates existing Chainloop hook entries.
  • Cover both missing and available CLI cases with tests.
  • Keep Git pre-push requireTrace enforcement unchanged.

Codex support for this behavior is being added in #3684. This issue tracks the remaining Claude Code and Cursor hooks.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions