harness-trace

harness-trace

Agent behavior recording layer for Claude Code. Records structured side-effect events (tool calls, skill activations, file I/O, git state) to local JSONL and uploads asynchronously to a team backend. Distributed as a Claude Code Plugin.

This is a recording layer. Analysis, dashboards, governance, and decisions belong to downstream projects in the harness-* family.

Install

Recommended: install at project scope per team repo. The plugin binds to the repo, travels with git, and leaves personal projects untouched.

# Add the team marketplace (once per user)
/plugin marketplace add <your-team-marketplace-url>

# In each team repo where you want tracking:
cd <team-repo>
/plugin install harness-trace --scope project

This writes .claude/settings.json with an enabledPlugins entry (commit it — teammates will be auto-prompted to install when they git pull).

Claude Code will prompt for ingest_endpoint (optional — leave empty for local-only mode) and ingest_token (optional).

Less common alternatives:

• --scope user: enable for all projects on your machine. Fine if you want telemetry everywhere.
• --scope managed: admin-enforced via organization settings.
• --scope local: per-repo override that stays out of git (via .claude/settings.local.json).

To disable in a specific repo you do want tracked by default, add to .claude/settings.local.json:

{ "enabledPlugins": { "harness-trace@<marketplace>": false } }

Uninstall / Disable

Use official Claude Code commands:

/plugin disable harness-trace
/plugin enable harness-trace
/plugin uninstall harness-trace

Commands

• /harness-trace:status — local collection health (last event age, queue depth, upload lag, errors)
• /harness-trace:push — manually trigger upload

What it records / does not record

Records (structured metadata only):

• Tool calls — name, args metadata (paths, offsets, hashes), duration, status, errno
• Skill / Rule / Subagent activations — name, source, content hash, token count
• File side-effects — path, blob SHA before/after, bytes/lines delta
• Git state — repo id, branch, commit SHA, dirty flag
• Session / turn skeleton — IDs, stop reasons, token counts

Does NOT record (internal state):

• Prompt text, tool output text, model output, thinking content
• Full file contents, full diffs
• Bash command raw text (parsed to structured segments instead)
• WebFetch URL path (only domain retained)

Hard guarantees (enforced in code):

• Secrets (env vars, JWTs, bearer tokens, API keys) auto-redacted
• File contents never duplicated — only (path, blob_sha, range) stored

Data location

• Events: ${CLAUDE_PLUGIN_DATA}/events-YYYY-MM-DD.jsonl
• State: ${CLAUDE_PLUGIN_DATA}/state/upload-offset.json
• Per-repo uuid: .git/harness-repo-id (written once, stable across remote migrations)

${CLAUDE_PLUGIN_DATA} resolves to ~/.claude/plugins/data/harness-trace-<marketplace>/.

License

MIT