Codex Session Forensics

codex-session-forensics is a small local CLI for answering questions like:

• "Which Codex session most likely created commit 98d7b4d1?"
• "Did this change come from an interactive Codex worktree?"
• "Was this commit produced by a workflow-run branch or a manual Codex session?"

It is a local-evidence ranking tool. It does not prove authorship.

What it uses

• your local git repo metadata
• your local Codex session database in ~/.codex
• nearby Codex logs that mention matching files or git actions

No network access is required for the tool itself.

Requirements

• Node.js 18+
• git
• sqlite3 CLI
• a local Codex home directory, usually ~/.codex

Install

Run directly from the repo:

node scripts/find-codex-session-for-commit.js 98d7b4d1

Or install the command globally from the repo checkout:

npm link
codex-session-forensics 98d7b4d1

Usage

codex-session-forensics [options] <commit> [<commit> ...]

Examples:

codex-session-forensics 98d7b4d1
codex-session-forensics --limit 3 345337d5 298b80f6
codex-session-forensics --json e5944cfc
codex-session-forensics --repo-root /absolute/repo/path 98d7b4d1
codex-session-forensics --state-db ~/.codex/state_7.sqlite 98d7b4d1

Output

For each commit, the tool prints:

• commit subject and timestamp
• top candidate Codex sessions
• confidence and score
• why each candidate matched
• nearby evidence rows from the Codex log store

Confidence is heuristic:

• high: strong time/cwd/git-action alignment
• medium: useful evidence, but incomplete or indirect
• low: weak lead only

Skill

This repo includes a Codex skill at:

skills/codex-session-forensics/SKILL.md

Install it into your Codex skills directory with:

npm run install-skill

By default this installs to:

• $CODEX_HOME/skills/codex-session-forensics, or
• ~/.codex/skills/codex-session-forensics

Notes

• The tool prefers the nearest matching git add, git commit, or git push logs over broad branch containment.
• Workflow-run branches can look different from interactive worktree sessions; the tool calls that out when it can.
• Different Codex installs may use different state_*.sqlite filenames. The tool auto-selects the newest local state DB if one is not specified.

License

MIT