Log Working-Directory Changes for a Session Path Trail

A tool-call log shows file paths but not necessarily what directory the agent was reasoning from at each point. This records every directory change, so a reviewer can reconstruct the session's path trail without inferring it from individual commands.

File & Environment Change Monitoring Event: CwdChanged Claude Code Open source · Free

1. Save this as the hook script

#!/usr/bin/env python3
"""CwdChanged hook — logs every working-directory change."""
import json, sys, datetime
from pathlib import Path

data = json.load(sys.stdin)
log_path = Path(data.get("cwd", ".")) / ".claude" / "cwd_change_log.jsonl"
log_path.parent.mkdir(parents=True, exist_ok=True)

entry = {"ts": datetime.datetime.utcnow().isoformat() + "Z",
         "previous_cwd": data.get("previous_cwd"), "new_cwd": data.get("new_cwd")}
with open(log_path, "a") as f:
    f.write(json.dumps(entry) + "\n")

sys.exit(0)

Save to a path inside your project, e.g. .claude/hooks/log-cwd-changes-path-trail.sh, then chmod +x it.

2. Wire it into .claude/settings.json

{
  "hooks": {
    "CwdChanged": [
      {
        "hooks": [
          {"type": "command", "command": "python3 .claude/hooks/log-cwd-changes-path-trail.py"}
        ]
      }
    ]
  }
}

Before you use this

A hook runs with your local shell's permissions — review the script above before adding it, the same way you'd review any script you didn't write yourself. See our guide on hook security risks for the specific CVEs this category of feature has already produced.

Related hooks

Alert on .env File Change Outside a Hook-Controlled Edit
Flags whenever a watched .env or .envrc file changes on disk, regardless of what triggere…
Block Project-Settings Changes Without a Reviewer Flag
Blocks a change to the project's checked-in .claude/settings.json unless a reviewer env v…
Detect a Symlink Swap on a Watched Compliance File
Flags if a newly-created file at a watched path is actually a symlink pointing outside th…
Record Baseline File Hashes for Compliance-Critical Files
Hashes a configured list of compliance-critical files at every session start, for later t…
← All hooks
FEEDBACK