claude-logger

Tamper-proof audit logger for AI coding agents. Hash-chained, append-only, SIEM-ready. Supports Claude Code, Cursor, Codex CLI, Aider, and any agent via generic stdin adapter.

---

Tamper-proof, verifiably

Every log entry is SHA-256 hash-chained. Files are marked append-only at the OS level. The monitored agent cannot erase its own evidence.

---

What it does

Hooks into every AI-agent event and writes a forensic-grade audit trail to $CLAUDE_LOGGER_DIR (default: ~/Claude Logs/).

• 12 Claude Code hook events captured — plus adapters for Cursor, Codex, Aider, any agent
• SHA-256 hash chain per entry — tampering is detectable
• macOS append-only flag (chflags uappnd) + Linux append-only (chattr +a) — OS-enforced immutability
• Parallel JSONL output — SIEM-ready (Splunk, Loki, Elastic, any jq-able pipeline)
• Multi-model cost tracking — Opus/Sonnet/Haiku auto-detected; per-session $ and $/hr
• 20+ secret redaction patterns — OpenAI, GitHub, AWS, Slack, JWT, Supabase, SendGrid, private keys
• Severity classification — RFC 5424 (INFO / NOTICE / WARN / ERROR / CRITICAL)
• Git context snapshots — branch, HEAD before/after, commits made during session, diff stat
• File hotspot tracking — parameterized SQLite, top-N most-touched files per project
• Zero duplicates — atomic dedup via tool_use_id
• Health heartbeat — optional cron-based monitor alerts during active hours (08:00–23:00 local) if logger goes silent

---

Install (one command)

For any user, any system:

curl -fsSL https://raw.githubusercontent.com/filmy-munky/claude-logger/main/install.sh | bash

Or clone + install locally:

git clone https://github.com/filmy-munky/claude-logger.git
cd claude-logger
./install.sh

Custom log location — set before install:

export CLAUDE_LOGGER_DIR="$HOME/my-ai-logs"
curl -fsSL https://raw.githubusercontent.com/filmy-munky/claude-logger/main/install.sh | bash

Requirements

Tool	macOS install	Linux install
jq	brew install jq	sudo apt install jq
shasum	pre-installed	part of perl
sqlite3	brew install sqlite3	sudo apt install sqlite3

What gets installed

~/.claude/
├── settings.json         ← 12 hook events wired
├── hooks/
│   ├── claude-logger.sh
│   ├── verify-log-integrity.sh
│   ├── logger-health-check.sh
│   └── adapters/
│       ├── cursor-adapter.sh
│       ├── codex-adapter.sh
│       ├── aider-adapter.sh
│       └── generic-adapter.sh
└── skills/
    └── claude-logger/
        └── SKILL.md       ← invokable via /skills in Claude Code

$CLAUDE_LOGGER_DIR/          (default: ~/Claude Logs/)
├── project_<name>_logs_YYYY-MM.md    ← human-readable, append-only
├── .project_<name>_YYYY-MM.jsonl     ← SIEM structured
├── .project_<name>_hotspots.db       ← SQLite file tracking
├── .hashchain/                        ← SHA-256 per project/month
└── .logger_heartbeat                  ← health monitor

---

Supported AI Agents

Agent	Integration	Status
Claude Code	Native — 12 hook events auto-wired via settings.json	✅
Cursor	cursor-adapter.sh — wire in Cursor hooks (beta)	✅
Codex CLI	codex-adapter.sh — pipe Codex event JSON	✅
Aider	aider-adapter.sh — shell wrapper or log post-processing	✅
GitHub Copilot CLI	Use generic-adapter.sh with structured wrapper	✅
Custom agent	Pipe JSON to generic-adapter.sh	✅

Generic integration example:

echo '{
  "source": "my-agent",
  "session_id": "session-abc123",
  "event": "tool_call",
  "tool": "FileEdit",
  "status": "success",
  "cwd": "/path/to/project",
  "detail": "edited src/main.py"
}' | ~/.claude/hooks/adapters/generic-adapter.sh

---

Security posture — framework-mapped

Before installing: your AI agent has no tamper-proof audit trail. After:

Metric	Before	After
Logging-domain maturity	0.5 / 5	4.5 / 5
Events logged	0	12+ types
Tamper detection	—	SHA-256 hash chain
Tamper prevention	—	Append-only FS flag
Secret redaction	—	20+ patterns
Access control	644 (default)	600 / 700
Structured output	—	JSONL (SIEM-ready)

Full framework mapping: BENCHMARK.md — mapped to NIST CSF 2.0 (2024), ISO/IEC 27001:2022 A.8.15/A.8.16/A.8.17, PCI DSS v4.0.1 Req 10, OWASP ASVS 5.0 Chapter V8, NIST SP 800-53 Rev 5 AU family, CIS Controls v8.1 Control 8, SOC 2 TSC 2017 (rev. 2022) CC6/CC7, GDPR Art. 5 & 32.

Scope: logging & monitoring domain only. Not a holistic compliance certification.

---

Example output — Markdown log

# claude-logger — my-app (2026-04)

> Schema version: 5
> Integrity: SHA-256 hash chain at `.hashchain/my-app_2026-04.hash`
> Immutability: append-only flag enforced

## 2026-04-13

| `2026-04-13T09:15:02Z` | **Edit** | success | `a1b2c3d4-...` | _PostToolUse_ | INFO |
> file_path=/app/main.py, old_string=def login():, new_string=def login(user_id):
> _integrity: 8b60cc7122256146_

| `2026-04-13T09:17:23Z` | **Bash** | FAILED | `a1b2c3d4-...` | _PostToolUseFailure_ | ERROR |
> command=npm test
> _integrity: f9bffa1d723487a8_

### SESSION SUMMARY — `a1b2c3d4-5e6f-7890-abcd-ef1234567890`

| Metric | Value |
|---|---|
| Duration | 1h 23m 45s |
| New commits | 3 |
| Model | claude-opus-4-6 |
| Total tokens | 14,415,648 |
| Estimated cost | $34.03 |
| Cost rate | $24.50/hr |

See examples/sample-output.md and examples/working-proof.txt for complete captures.

---

Example output — JSONL (SIEM-ready)

{"@timestamp":"2026-04-13T09:17:23Z","schema_version":"5","agent_source":"claude-code","severity":"ERROR","event":"PostToolUseFailure","tool":"Bash","session_id":"a1b2c3d4-...","project":"my-app","integrity_hash":"8b60cc7122..."}

Query with jq, ship to Splunk/Loki/Elastic, or wire into any SIEM.

---

Verify log integrity

~/.claude/hooks/verify-log-integrity.sh my-app 2026-04
# → PASS: Hash chain intact (247 entries, no gaps)

Any tampering (inserted, deleted, or modified entries) breaks the chain.

---

Query your logs

# Most expensive sessions this month
grep -A 15 "SESSION SUMMARY" ~/Claude\ Logs/project_*_logs_$(date +%Y-%m).md

# All errors across all projects
jq 'select(.severity=="ERROR")' ~/Claude\ Logs/.project_*.jsonl

# Total cost this month
grep -hE "Estimated cost" ~/Claude\ Logs/project_*_logs_$(date +%Y-%m).md | \
  awk '{gsub(/[^0-9.]/, "", $NF); sum += $NF} END {printf "$%.2f\n", sum}'

# Top 10 most-edited files
for db in ~/Claude\ Logs/.project_*_hotspots.db; do
  sqlite3 "$db" "SELECT count, file FROM hotspots ORDER BY count DESC LIMIT 10;"
done | sort -t'|' -k1 -nr | head -10

In Claude Code, type /skills and invoke the claude-logger skill for guided queries.

---

Uninstall

curl -fsSL https://raw.githubusercontent.com/filmy-munky/claude-logger/main/uninstall.sh | bash
# or from clone:
./uninstall.sh

Removes hooks + skill. Logs are preserved (not deleted).

---

Screenshots

Logs folder structure	Tamper test + integrity verification

---

FAQ

Does this slow down my AI agent? No. All hooks run async: true — zero blocking time (~30-50ms per hook invocation).

Can the AI tamper with its own logs? No (under the threat model). chflags uappnd (macOS) / chattr +a (Linux) make log files append-only at the OS level for non-root processes. Modification or deletion attempts fail with operation not permitted. Scope caveat: a privileged user (root/admin) can always clear these flags.

Will it leak secrets? Defense in depth: (1) allowlist field logging, (2) 20+ regex redactions, (3) value truncation. Secrets in tool outputs are NOT logged — only input summaries.

What if my agent isn't listed? Use generic-adapter.sh with any structured JSON payload. See "Generic integration example" above.

How does this map to SOC 2 logging criteria? See BENCHMARK.md for control-by-control mapping. Confirmed PASS: CC6.1 (logical access to logs), CC7.2 (system monitoring). PARTIAL: CC7.3 (no alerting pipeline). FAIL: CC6.7 (no encryption at rest — permissions ≠ encryption).

Linux support? Yes. Append-only uses chattr +a instead of chflags uappnd. Everything else is identical.

---

Credits

Built by Punith Gowda - @filmy-munky. Framework-mapped against NIST CSF 2.0, ISO/IEC 27001:2022, PCI DSS v4.0.1, OWASP ASVS 5.0, NIST SP 800-53 Rev 5, CIS Controls v8.1, SOC 2 TSC 2017 (rev. 2022), and GDPR Art. 5 & 32.

MIT License. Runtime dependencies: jq, shasum, and sqlite3 (optional — file hotspots).