Codex CLI — SessionStart hook announces peepshow to the model.

How it plugs in

Codex CLI's hook system is a natural fit: the SessionStart hook emits a one-line reminder about peepshow into the model's context. When Codex sees a video path, it uses its Bash tool to call the CLI.

Install

git clone --depth 1 https://github.com/t0mtaylor/peepshow.git
# Codex picks up .codex/hooks.json + .codex/config.toml on next session.

Files involved

• .codex/hooks.json SessionStart hook — announces peepshow.
• .codex/config.toml Optional default flags and sink presets.

In practice

user: open bug-report.mov
codex: (Bash: peepshow ./bug-report.mov --emit json) → frames → answer

All 95 sinks still work

The CLI is the same across agents — which means every sink documented under /sinks is available here. Auto-sinks fire regardless of which agent invoked peepshow.

Report + LLM analysis loop

Every run also writes a self-contained report.html + manifest.json next to the frames (see the Report page). When Codex CLI consumes the frames, the analysis flows back into the report so whoever opens it next sees the model's understanding without re-running the prompt.

echo '{"summary":"<your summary>","provider":"codex"}' \
  | peepshow report annotate "<outputDir>"

The annotate instruction is wired into the Codex CLI integration — the agent runs it after reading the frames + transcript. Report walkthrough →