{
  "markdown": "# claude-chronicle\n\n![claude-chronicle — Codex Chronicle's screen-recording memory, piped into Claude Code](assets/hero.png)\n\n> Bring Codex Chronicle's screen-recording memory into Claude Code. Ask Claude *\"what was I doing 5 hours ago?\"* or *\"when did I last touch the auth bug?\"* and get a real answer.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Plugin version](https://img.shields.io/badge/version-0.4.1-blue.svg)](CHANGELOG.md)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-7C3AED.svg)](https://code.claude.com/docs/en/plugins)\n\n[Codex Chronicle](https://github.com/openai/codex) passively records your screen, runs OCR, and writes a markdown summary every ~10 minutes describing what you have been doing across your apps. **claude-chronicle** is a Claude Code plugin that pipes those summaries into Claude Code as context, so Claude knows what you have been working on outside the terminal — past activity, current focus, and the live screen.\n\n## What it does\n\nTwo hooks, one script:\n\n- **`SessionStart`** — when Claude Code starts, injects:\n  1. The **3 most recent** 10-minute Chronicle summaries as full content (current focus).\n  2. A **manifest of every Chronicle entry on disk** — timestamps, relative ages, absolute paths — so Claude knows the full memory window and can `Read` any older entry on demand.\n  3. A **Chronicle live state** section — pidfile health, freshest screen frames per display, OCR sidecar locations, and a usage guide that tells Claude *which* source to reach for given the kind of question.\n- **`UserPromptSubmit`** — on every prompt, checks for **new** Chronicle entries that appeared since the last injection and adds only those. Stays silent if there is nothing new.\n\nBoth events skip the `## Recording summary` and `## Citations` sections of each Chronicle file (raw OCR detail and frame paths). Claude sees the `## Memory summary`, `### Context of everything that came before this recording`, and `### Important non-obvious context about the user` sections.\n\n### Asking about earlier activity\n\nBecause the SessionStart manifest lists **every** Chronicle file with its local timestamp and \"Xh ago\" tag, you can ask about anything in that window and Claude will pick the right file(s) and read them:\n\n| English | Polski |\n|---|---|\n| \"What was I doing 5 hours ago?\" | \"Co robiłem 5 godzin temu?\" |\n| \"What was I working on yesterday evening?\" | \"Nad czym pracowałem wczoraj wieczorem?\" |\n| \"What project was I on the day before yesterday around noon?\" | \"Przedwczoraj nad południem nad jakim projektem siedziałem?\" |\n| \"Summarize my whole week.\" | \"Podsumuj mi cały tydzień.\" |\n\nNo regex / NLU in the hook — Claude does the time reasoning over the manifest table itself, then uses the `Read` tool to pull only the entries it actually needs.\n\n### `/claude-chronicle:remind` — on-demand recall\n\nFor a force-fresh search of the Chronicle archive (e.g. when the SessionStart manifest has been compacted out of context), invoke the bundled skill. It supports three auto-detected modes:\n\n**1. By time** — you remember when, not what:\n\n```\n/claude-chronicle:remind 5 hours ago\n/claude-chronicle:remind wczoraj wieczorem\n/claude-chronicle:remind Tuesday afternoon\n/claude-chronicle:remind 30 minut temu\n```\n\n**2. By topic** — you remember what, not when:\n\n```\n/claude-chronicle:remind the auth bug\n/claude-chronicle:remind React 418 error\n/claude-chronicle:remind projekt logo w Figmie\n/claude-chronicle:remind ta migracja SQL z poniedziałku\n```\n\nThe skill `rg`-greps the whole Chronicle archive for your keyword(s), reports **when** you last touched the topic, and summarises what you were doing then.\n\n**3. Hybrid** — both signals at once:\n\n```\n/claude-chronicle:remind the auth bug yesterday\n/claude-chronicle:remind Figma logo last week\n/claude-chronicle:remind ten error 418 wczoraj wieczorem\n```\n\nThe skill narrows by time first, then keyword-greps inside that window.\n\nIn all three modes the skill runs autonomously (no \"do you want me to read X?\" prompts), reads only the picked entries, skips the noisy `Recording summary` / `Citations` sections, and answers in your language (PL → PL, EN → EN), naming the source filename(s) so you can verify.\n\n### Looking at the screen\n\nThe live state section also exposes the ephemeral screen-recording side of Chronicle:\n\n- **Live frames** (`*-display-N-latest.jpg`) per display, refreshed by the recorder. Useful for \"what's on my screen right now?\".\n- **OCR sidecars** (`*.ocr.jsonl`) — append-only OCR text history. Useful for `rg`-style searches like \"where did I see this error?\".\n- **1-minute historical frames** (`1min/<segment>/frame-*.jpg`).\n\nThe injected guidance teaches Claude to (a) prefer authoritative sources (connectors, file system) over OCR'd screen text, (b) copy `latest.jpg` to a temp file before manipulating it (the recorder silently overwrites the original), and (c) use OCR only for keyword search, not for verbatim text extraction.\n\n## Prerequisites\n\n- macOS or Linux\n- `bash` 3.2+ (the macOS default works) and `jq` available in `PATH`\n- [Codex CLI](https://github.com/openai/codex) installed and Chronicle enabled, writing to `~/.codex/memories_extensions/chronicle/resources/`\n\nIf Chronicle is not active or the directory is empty, the plugin exits silently — it never breaks a Claude Code session.\n\n## Installation\n\n### Option A — via this marketplace (recommended)\n\nInside Claude Code:\n\n```\n/plugin marketplace add wojciechkapala/claude-chronicle\n/plugin install claude-chronicle@claude-chronicle\n```\n\nThen restart Claude Code. Updates: `/plugin update claude-chronicle@claude-chronicle`.\n\n### Option B — load directly from a local clone\n\n```bash\ngit clone https://github.com/wojciechkapala/claude-chronicle.git\nclaude --plugin-dir ./claude-chronicle\n```\n\n### Option C — copy into the user plugin dir\n\n```bash\ngit clone https://github.com/wojciechkapala/claude-chronicle.git ~/.claude/plugins/claude-chronicle\n```\n\nThen restart Claude Code. Hooks load on session start, so any change to `hooks/hooks.json` requires a restart.\n\n## Configuration\n\nAll optional, controlled via environment variables:\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `CODEX_CHRONICLE_DIR` | `~/.codex/memories_extensions/chronicle/resources` | Directory containing `*-10min-*.md`  files |\n| `CODEX_CHRONICLE_BOOTSTRAP_N` | `3` | How many recent entries to inline as full content on `SessionStart` |\n| `CODEX_CHRONICLE_MAX_AGE_HOURS` | `12` | Window for the \"full content\" entries on `SessionStart` (manifest is unaffected) |\n| `CODEX_CHRONICLE_MANIFEST_MAX` | `500` | Hard cap on how many entries to list in the manifest table (most recent are kept) |\n| `CODEX_CHRONICLE_LIVE_DIR` | `$TMPDIR` | Root for Chronicle's ephemeral state — expects `<dir>/codex_chronicle/chronicle-started.pid` and `<dir>/chronicle/screen_recording/` |\n\nSet them in your shell profile (`~/.zshrc`, `~/.bashrc`) before starting Claude Code.\n\n## Runtime state\n\nThe plugin tracks the newest Chronicle entry it has already shown in `${CLAUDE_PLUGIN_ROOT}/.state/last-seen.txt` (epoch seconds). This is what keeps `UserPromptSubmit` silent until a genuinely new file appears. Delete the file to re-inject everything on the next prompt.\n\n## Debugging\n\n### Run the script manually\n\nPoint `PLUGIN_DIR` at wherever you cloned or installed the plugin (e.g. `~/.claude/plugins/claude-chronicle` for Option C, or your local clone):\n\n```bash\nPLUGIN_DIR=~/.claude/plugins/claude-chronicle\n\necho '{\"hook_event_name\":\"SessionStart\",\"session_id\":\"test\"}' \\\n  | CLAUDE_PLUGIN_ROOT=\"$PLUGIN_DIR\" \\\n    bash \"$PLUGIN_DIR/hooks/scripts/inject-chronicle-context.sh\" \\\n  | jq .\n```\n\nExpected: a JSON object with `systemMessage` containing your latest activity. With no new files since the last `SessionStart`, the same command for `UserPromptSubmit` returns `{\"continue\":true,\"suppressOutput\":true}`.\n\n### Tail the debug log inside Claude Code\n\n```bash\nclaude --debug --plugin-dir ~/.claude/plugins/claude-chronicle\n```\n\nLook for `SessionStart` hook execution and the injected `systemMessage`.\n\n## Limitations\n\n- Hook configuration is loaded once at session start. Editing `hooks.json` or the script does not affect the running session — restart Claude Code.\n- 6-hour rollups (`*-6h-*.md`) are picked up automatically alongside `*-10min-*.md` files (the manifest tags them with `Kind = 6h`), but Chronicle only generates them after running for several hours, so they may not exist yet on a given machine.\n- The `last-seen` cursor is global (one file across all sessions), not per-session. This works because Chronicle writes new files in chronological order.\n\n## License\n\nMIT\n",
  "bytes": 8680,
  "sha": "c8b2401fec27e03e3aa8448c0b1c695d460abdad71cc565b2a94bc88f2aee052",
  "repo_slug": "wojciechkapala/claude-chronicle",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_wojciechkapala_claude_chronicle_claude_c_7d9530ea/readme"
}