claude-chronicle
Bridges Codex Chronicle's screen-recording memory into Claude Code. Codex Chronicle is an OpenAI Codex feature that passively records your s
Open source Repository Open in the app JSON README (API)
About
Bridges Codex Chronicle's screen-recording memory into Claude Code. Codex Chronicle is an OpenAI Codex feature that passively records your screen, runs OCR, and writes a markdown summary every ~10 minutes describing what you have been doing across your apps. This plugin pipes those summaries into Claude Code via SessionStart and UserPromptSubmit hooks, so Claude knows what you have been working on outside the terminal — past activity, current focus, and the live screen. Ships with a /claude-chronicle:remind skill that searches the archive by time, topic, or both.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- wojciechkapala
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 1
- Last push
- 2026-04-25T11:20:31Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
wojciechkapala/claude-chronicle/claude-chronicle
README
# claude-chronicle
> 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.
[](LICENSE)
[](CHANGELOG.md)
[](https://code.claude.com/docs/en/plugins)
[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.
## What it does
Two hooks, one script:
- **`SessionStart`** — when Claude Code starts, injects:
1. The **3 most recent** 10-minute Chronicle summaries as full content (current focus).
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.
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.
- **`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.
Both 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.
### Asking about earlier activity
Because 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:
| English | Polski |
|---|---|
| "What was I doing 5 hours ago?" | "Co robiłem 5 godzin temu?" |
| "What was I working on yesterday evening?" | "Nad czym pracowałem wczoraj wieczorem?" |
| "What project was I on the day before yesterday around noon?" | "Przedwczoraj nad południem nad jakim projektem siedziałem?" |
| "Summarize my whole week." | "Podsumuj mi cały tydzień." |
No 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.
### `/claude-chronicle:remind` — on-demand recall
For 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:
**1. By time** — you remember when, not what:
```
/claude-chronicle:remind 5 hours ago
/claude-chronicle:remind wczoraj wieczorem
/claude-chronicle:remind Tuesday afternoon
/claude-chronicle:remind 30 minut temu
```
**2. By topic** — you remember what, not when:
```
/claude-chronicle:remind the auth bug
/claude-chronicle:remind React 418 error
/claude-chronicle:remind projekt logo w Figmie
/claude-chronicle:remind ta migracja SQL z poniedziałku
```
The 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.
**3. Hybrid** — both signals at once:
```
/claude-chronicle:remind the auth bug yesterday
/claude-chronicle:remind Figma logo last week
/claude-chronicle:remind ten error 418 wczoraj wieczorem
```
The skill narrows by time first, then keyword-greps inside that window.
In 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.
### Looking at the screen
The live state section also exposes the ephemeral screen-recording side of Chronicle:
- **Live frames** (`*-display-N-latest.jpg`) per display, refreshed by the recorder. Useful for "what's on my screen right now?".
- **OCR sidecars** (`*.ocr.jsonl`) — append-only OCR text history. Useful for `rg`-style searches like "where did I see this error?".
- **1-minute historical frames** (`1min/<segment>/frame-*.jpg`).
The 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.
## Prerequisites
- macOS or Linux
- `bash` 3.2+ (the macOS default works) and `jq` available in `PATH`
- [Codex CLI](https://github.com/openai/codex) installed and Chronicle enabled, writing to `~/.codex/memories_extensions/chronicle/resources/`
If Chronicle is not active or the directory is empty, the plugin exits silently — it never breaks a Claude Code session.
## Installation
### Option A — via this marketplace (recommended)
Inside Claude Code:
```
/plugin marketplace add wojciechkapala/claude-chronicle
/plugin install claude-chronicle@claude-chronicle
```
Then restart Claude Code. Updates: `/plugin update claude-chronicle@claude-chronicle`.
### Option B — load directly from a local clone
```bash
git clone https://github.com/wojciechkapala/claude-chronicle.git
claude --plugin-dir ./claude-chronicle
```
### Option C — copy into the user plugin dir
```bash
git clone https://github.com/wojciechkapala/claude-chronicle.git ~/.claude/plugins/claude-chronicle
```
Then restart Claude Code. Hooks load on session start, so any change to `hooks/hooks.json` requires a restart.
## Configuration
All optional, controlled via environment variables:
| Variable | Default | Purpose |
|---|---|---|
| `CODEX_CHRONICLE_DIR` | `~/.codex/memories_extensions/chronicle/resources` | Directory containing `*-10min-*.md` files |
| `CODEX_CHRONICLE_BOOTSTRAP_N` | `3` | How many recent entries to inline as full content on `SessionStart` |
| `CODEX_CHRONICLE_MAX_AGE_HOURS` | `12` | Window for the "full content" entries on `SessionStart` (manifest is unaffected) |
| `CODEX_CHRONICLE_MANIFEST_MAX` | `500` | Hard cap on how many entries to list in the manifest table (most recent are kept) |
| `CODEX_CHRONICLE_LIVE_DIR` | `$TMPDIR` | Root for Chronicle's ephemeral state — expects `<dir>/codex_chronicle/chronicle-started.pid` and `<dir>/chronicle/screen_recording/` |
Set them in your shell profile (`~/.zshrc`, `~/.bashrc`) before starting Claude Code.
## Runtime state
The 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.
## Debugging
### Run the script manually
Point `PLUGIN_DIR` at wherever you cloned or installed the plugin (e.g. `~/.claude/plugins/claude-chronicle` for Option C, or your local clone):
```bash
PLUGIN_DIR=~/.claude/plugins/claude-chronicle
echo '{"hook_event_name":"SessionStart","session_id":"test"}' \
| CLAUDE_PLUGIN_ROOT="$PLUGIN_DIR" \
bash "$PLUGIN_DIR/hooks/scripts/inject-chronicle-context.sh" \
| jq .
```
Expected: 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}`.
### Tail the debug log inside Claude Code
```bash
claude --debug --plugin-dir ~/.claude/plugins/claude-chronicle
```
Look for `SessionStart` hook execution and the injected `systemMessage`.
## Limitations
- Hook configuration is loaded once at session start. Editing `hooks.json` or the script does not affect the running session — restart Claude Code.
- 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.
- The `last-seen` cursor is global (one file across all sessions), not per-session. This works because Chronicle writes new files in chronological order.
## License
MIT