Claude Code collector
The collector is a small CLI that connects Claude Code to Tracemason using Claude Code's documented hooks.
Install
npx @tracemason/cli init
Pre-release:
@tracemason/cliis being published to npm. Until it is listed there, this command will not resolve.
That is the whole installation. It needs Node.js 20 or later and reports to the hosted service at app.tracemason.com; for your own server add --endpoint <url> (see Self-hosting).
The collector is one file with no dependencies. init copies it to ~/.tracemason/bin/tracemason.mjs and points the hooks there, so nothing depends on the npx cache or on a global install. The other commands run the same way: npx @tracemason/cli status, test, flush, uninstall. To update, run npx @tracemason/cli@latest init again.
init does five things and prints each one:
- Authorizes the machine. It shows a short code and opens your browser. You sign in, choose the organization and approve. No key is typed or pasted.
- Stores credentials in
~/.tracemason/config.json, readable only by you (mode 0600). - Installs itself and configures hooks in your Claude Code settings file.
- Optionally enables telemetry export (
--with-otel), see OpenTelemetry. - Sends a test event and confirms the server accepted it.
Options
| Flag | Meaning |
|---|---|
--endpoint <url> |
A self-hosted Tracemason server. Must be https, except localhost. Default: https://app.tracemason.com. |
--scope user|project|local |
Which settings file to write. user (default) is ~/.claude/settings.json; project is .claude/settings.json; local is .claude/settings.local.json. |
--name <name> |
Name shown for this machine in the dashboard. |
--environment <name> |
Declare an environment for this machine's sessions. Unverified until an admin confirms it. |
--with-otel |
Also export Claude Code's native telemetry (log events). |
--no-browser |
Print the approval URL instead of opening it. |
Hooks installed
SessionStart, SessionEnd, PreToolUse, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop, Stop.
Each is a command hook that runs tracemason hook. Existing hooks and other settings in the file are preserved, and Tracemason's entries can be removed cleanly with npx @tracemason/cli uninstall.
What a hook does
- Reads the hook payload from stdin.
- Builds a structured event from it — see What is collected.
- Appends the event to a local queue and exits. It never waits on the network; in testing a hook takes about 60 ms.
- A separate background process delivers the queue in batches.
If anything inside the hook fails, it exits 0 with no output, which Claude Code treats as "no opinion". The collector is never the reason a tool call fails.
Reliability
- Bounded queue. At most 5,000 events or 8 MB are kept locally. Beyond that the oldest are dropped.
- Nothing is dropped silently. Dropped events are counted and reported to the server with the next successful batch; the dashboard shows the collector as degraded.
- Retries with backoff. Delivery failures back off exponentially (2 s up to 5 min, with jitter).
- Idempotent. A batch is removed from disk only after the server acknowledges it, and event ids make redelivery safe.
Check the collector at any time:
npx @tracemason/cli status # configuration, hooks, queue depth, drops, connectivity
npx @tracemason/cli test # send a test event now
npx @tracemason/cli flush # deliver the queue now
Monitoring, advisory and enforcement
Each policy has a mode, set under Security → Policies.
- Monitor — matches become findings. Nothing changes for the developer.
- Advisory — when the collector sees a match on
PreToolUse, it returnspermissionDecision: "ask"so Claude Code asks the developer to confirm. - Enforce — the collector returns
permissionDecision: "deny"with a reason. The event is recorded as blocked, and the finding is marked blocked.
Policies in advisory or enforce mode are evaluated on the developer's machine from a cached copy (refreshed at most once a minute), so the decision does not depend on the network.
What enforcement is not
Hooks run on a machine the developer controls. They can be removed, and Claude Code can be run without them. Enforcement here is a guardrail, not a security boundary. "Blocked" in Tracemason means precisely: the hook returned a deny decision through Claude Code's documented mechanism. For controls that must hold, use repository permissions, branch protection, sandboxes, CI policy and infrastructure authorization.
Two kinds of policy cannot be enforced locally, because they depend on facts only the server knows: restricted repositories and verified production environments. These always behave as monitor.
Linking commits
When Claude runs a commit command, the collector reads HEAD before and after the tool call. If it moved, the new SHA is recorded on the event. If the GitHub integration later reports the same SHA, the link is Verified. You can also link explicitly by adding a trailer to a commit message or PR description:
Tracemason-Session: <session id>
Uninstall
npx @tracemason/cli uninstall # remove hooks from all settings files
npx @tracemason/cli uninstall --purge # also delete ~/.tracemason
Revoke the machine's key under Integrations → Ingestion keys to disable it server-side.