harness-tracker

Track file operations made by AI coding agents. One install, all projects.

harness-tracker hooks into Claude Code to record every Read, Edit, and Write operation to a local JSONL log. It gives you visibility into what your agent is doing with your files — which files it touches most, how often, and when.

Install

npm install -g harness-tracker

Prerequisites

• Node.js >= 20
• jq (used by the hook script)

  brew install jq  # macOS

Quick Start

# Register hooks in Claude Code
harness-tracker install

# Use Claude Code normally — operations are tracked automatically

# View file statistics
harness-tracker stats

# View recent operations
harness-tracker history

# View session overview
harness-tracker sessions

# Remove hooks (keeps existing data)
harness-tracker uninstall

Commands

harness-tracker install

Registers a PostToolUse hook in ~/.claude/settings.json. The hook runs after every Read, Edit, and Write operation and appends a record to the log.

Existing hooks are preserved — harness-tracker merges its configuration safely.

harness-tracker uninstall

Removes the hook from ~/.claude/settings.json. Log data is preserved in ~/.claude/harness-tracker/logs/.

harness-tracker stats [--project <path>]

Shows per-file operation counts (reads, edits, writes) and last access time, sorted by total operations.

File                                  Read  Edit  Write  Last Access
--------------------------------------------------------------
/src/components/App.tsx                 12     3      2  2026-03-23T14:30:08Z
/src/utils/helpers.ts                    8     1      1  2026-03-23T14:28:15Z

harness-tracker history [--limit N]

Shows the most recent N operations (default: 20) in chronological order.

Timestamp             Op     Path
--------------------------------------------------------------------------------
2026-03-23 14:30:01   Read   /src/main.ts
2026-03-23 14:30:05   Edit   /src/main.ts
2026-03-23 14:30:08   Write  /src/utils.ts [Explore]

harness-tracker sessions [--limit N]

Shows session overview with operation count and file count per session.

Data Format

Logs are stored as JSONL files in ~/.claude/harness-tracker/logs/, one file per day:

ops-2026-03-23.jsonl
ops-2026-03-24.jsonl

Each line is a JSON object with these fields:

| Field | Type | Present | Description | |-------|------|---------|-------------| | ts | string | always | ISO 8601 timestamp | | sid | string | always | Claude Code session ID | | op | string | always | Read, Edit, or Write | | path | string | always | Absolute file path | | offset | number | Read | Starting line offset | | limit | number | Read | Number of lines read | | old_len | number | Edit | Length of replaced text | | new_len | number | Edit | Length of new text | | size | number | Write | Total content size in bytes | | agent | string | subagent | Agent ID (when operation is from a subagent) | | agent_type | string | subagent | Agent type (e.g., Explore, Plan) |

Example:

{"ts":"2026-03-23T14:30:01Z","sid":"abc123","op":"Read","path":"/src/main.ts","offset":0,"limit":2000}
{"ts":"2026-03-23T14:30:05Z","sid":"abc123","op":"Edit","path":"/src/main.ts","old_len":45,"new_len":62}
{"ts":"2026-03-23T14:30:08Z","sid":"abc123","op":"Write","path":"/src/utils.ts","size":1823,"agent":"agent_03XYZ","agent_type":"Explore"}

How It Works

1. harness-tracker install adds a PostToolUse hook to ~/.claude/settings.json
2. When Claude Code executes a Read/Edit/Write, the hook script receives the operation details via stdin
3. The script extracts relevant fields and appends a JSONL record to ~/.claude/harness-tracker/logs/ops-YYYY-MM-DD.jsonl
4. The CLI commands read these JSONL files to generate reports

The hook script is a lightweight bash script (~30 lines) that targets < 5ms execution time.

License

MIT