chronicle

name	chronicle
description	Allows you to view the user's screen as well as several hours of history. Use when the user makes a reference to their recent work, for which it'd be helpful to see the screen. Use this skill only when screen context is the best way to resolve ambiguity in a user request. Do not use it for ordinary repo, GitHub, filesystem, or memory-context questions that can be answered from those sources directly. You must also use this skill if the user asks about any question regarding Chronicle or asks what you can see from the screen.
metadata	{"short-description":"Inspect recent screen context"}

Chronicle

This skill allows you to view the user's screen. This skill is enabled because the user has enabled the Codex screen recording (Chronicle) feature, which records a rolling buffer of the past several hours of work to $TMPDIR/chronicle/screen_recording.

Preconditions

1. Only use this skill if memories are available in this rollout. This will manifest as an explicit mention of a ## Memories section in a Developer Message. If this section is not present, do not use this skill. If the user specifically tried to invoke this skill, you can mention it's disallowed because memories are disabled; otherwise, do not mention the existence of this skill (this skill is only supposed to be used when memories are enabled in Codex).
2. Ensure Chronicle is running on the user's computer. Read the PID from $TMPDIR/codex_chronicle/chronicle-started.pid, verify that the process is running, and confirm the executable is codex_chronicle when host-visible process inspection is available. Do not trust sandbox-limited process checks as proof that Chronicle is running. If the pidfile is missing, stale, points at the wrong executable, or cannot be verified from the host, do not use this skill. This applies EVEN IF there are seemingly-fresh videos in the screen_recording folder; the user may have just recently disabled Chronicle. Regardless, the takeaway is that recordings cannot be fresh when Chronicle isn't running; therefore, you shouldn't treat the videos as fresh. If Chronicle is unavailable, proceed with other relevant context sources and do not mention Chronicle status unless the user explicitly asked for screen history, Chronicle, or what you can see on screen. When you do mention status, keep it brief and don't mention the pidfile; that's an implementation detail.

Ensure you follow preconditions before using the skill.

File structure

Chronicle has two primary outputs: screen recordings and memories.

# Raw screen recordings (ephemeral; not persisted)
$TMPDIR/chronicle/screen_recording/
 ├── <segment_timestamp>-display-<display_id>-latest.jpg
 │   Latest frame for this segment, overwritten on every captured frame
 ├── <segment_timestamp>-display-<display_id>.capture
 │   Ephemeral capture segment marker
 ├── <segment_timestamp>-display-<display_id>.capture.json
 │   Metadata for this segment; no app information
 ├── <segment_timestamp>-display-<display_id>.ocr.jsonl
 │   Append-only OCR history for material text changes
 └── 1min/
     └── <segment_timestamp>-display-<display_id>/
         └── frame-<frame_index>-<minute_bucket>Z.jpg
             Historical privacy-filtered frames

# Memories (persisted indefinitely; referenced in Codex Memories)
~/.codex/memories/extensions/chronicle/
  ├── instructions.md - instructions for how to use the Chronicle memories
  └── resources/
    ├── <utc_timestamp>-<4_alpha_chars>-10min-<slug_description>.md
    │   Summary of the last 10 minutes, updated every minute
    └── <utc_timestamp>-<4_alpha_chars>-6h-<slug_description>.md
        Summary of the last 6 hours, updated every hour

Memory Distillation

Persisted Chronicle summaries are source evidence, not active memory by themselves. During memory cleanup or distillation, do not promote a raw Chronicle observation into memory, a skill, or a durable handoff unless it is validated against a current source of truth such as a repo, branch, issue, PR, workflow run, release surface, local file, or explicit user confirmation. Drop personal/incidental app context, raw screen/OCR paths, and point-in-time CI, release, or PR facts that are not revalidated. Raw Chronicle resources may be distilled into a local-only report and then archived or deleted according to the user's retention decision.

Usage

The most common workflow is to read the latest frame of the screen recording for a given display, which represents the user's most recent work.

• Copy it to a temp file when you want to do file operations on it, because otherwise the file will be silently updated by the screen recording service.
• When you need recent screen history instead of only the latest frame, search the OCR sidecars first. Use rg over *.ocr.jsonl to find relevant terms or timestamps, then inspect the matching sparse frames in screen_recording/1min/ for visual confirmation.
• Historical frames are stored as individual files. Manipulate them as necessary to look at multiple frames to contextualize what the user was working on.
• The recorder can capture multiple displays at once. If the user asks what was happening recently, inspect current files for all active display IDs and combine evidence by timestamp.
• Screen recordings may not always be up-to-date. You must use the date command to get the current UTC timestamp and compare it against the recording files you're inspecting to understand if the recordings are fresh or stale (e.g. from a previous recording session).
• You should ONLY use the OCR for greps to find relevant terms or timestamps, not for any other purpose (e.g. extracting document IDs to send to connectors). This is because the OCR is very noisy and not very accurate. Instead, extract text from the image yourself when you need to do something with the text.
• Screen data should be used to get context on the user's work, but you must upgrade to other data sources (such as your app-specific skills, connectors, or the file system) as soon as you've gotten the minimum necessary context from the screen data to do so. This is because your multimodal understanding is not that good, so you should avoid relying on it for complex tasks.
  • For example, if the user asks you to "review the doc I have open", you should view the context, see that e.g. it's a Google Doc with a doc ID, extract the doc ID, and then use the Google Doc connector to review the doc. You must not try to OCR the entire document from the screenshot (also because the user's screen may not show the entire content of the document).