Chronicle

Chronicle

Record your screen and system events on your computer, write context files and workflows from them, and build them into LLM harnesses for any task. Any AI can use a harness over MCP or as downloaded files.

The full documentation covers the app, every command, and the API.

An agent usually starts each task with no knowledge of your computer. It doesn't know your ticket, your open file, or your last search, so you paste that context by hand. Chronicle keeps that memory on your computer and lets the agent request it:

• Continue your work. "Finish the Acme export" works because the agent can see export.ts, the status of PR 882, and the Notion spec.
• Teach by showing. Record a task once. The agent gets the apps, pages, and steps in order.
• Use tools without MCP. Download a harness as a .zip or one Markdown file for ChatGPT, Claude Projects, NotebookLM, Neo4j, or a RAG pipeline.

Chronicle stores everything in ~/.chronicle, with no account and no telemetry. See Privacy for what leaves your computer.

Quick start

Chronicle needs Python 3.10 or newer. macOS is the main platform, and Linux (X11) and Windows support is best effort.

These commands load a synthetic workday, so Chronicle records nothing.

uv tool install --python 3.12 "chronicle-context[graph]"

chronicle demo chronicle context "finish the Acme export"

chronicle context prints the Markdown that the get_context MCP tool returns. The sample output starts like this:

# Computer context (Chronicle)

Task: finish the Acme export Window: the most recent 2h of history.

What you were doing

• 14:55-15:31 meeting Acme weekly · Jordan Hale (36m)
• 15:34-16:24 writing customer emails · export spec (50m)
• 16:28-16:48 coding export.ts · asking Priya (20m)

On screen now

• Chrome · Checks · PR 882 (frame 18)
• URL: https://github.com/northwind/billing/actions

To open the app, connect an agent, and record your own work:

chronicle serve

chronicle mcp install cursor chronicle doctor chronicle record 30m --label "file an expense report"

The app runs at http://127.0.0.1:3030. chronicle mcp clients lists every client.

Permissions and tools

On macOS, the app that runs Chronicle is your terminal or the MCP host, such as Claude Desktop or Cursor. Add it under System Settings › Privacy & Security, then quit and reopen it. Closing its windows isn't enough.

How it works

Record. A session runs for a set time, such as 90s, 30m, or 2h, or until you stop it. Every 5 seconds by default, Chronicle samples the front app, its window, and the browser URL. When something changes, and at least every 30 seconds, Chronicle also takes a screenshot and reads screen text. Chronicle never records keystrokes, and it skips password managers, System Settings, and private browser windows.

Read sources. Under Privacy & Sources, you can also turn on Apple Mail, Calendar, iMessage, WhatsApp, browser history, folders, and AI tool logs. Every source starts off.

Build the graph. Each session gets its own graph. Nodes include apps, pages, files, tickets, PRs, people, topics, and tasks. Every node and edge records its time and its source frames, so an agent can cite its evidence. The all-history graph combines the sessions, and older sessions count less.

Write. With a model set up, Chronicle names the graph's work, then writes context files and workflows when a recording ends. Without a model, Chronicle runs offline and builds plain context files from the evidence.

Serve. Agents read everything over MCP.

Connect an agent

Local clients

chronicle mcp install adds Chronicle to a client's config and keeps a .chronicle-backup copy of the old file. chronicle mcp config prints the snippet and writes nothing.

Restart the client after an install. Only one Chronicle process captures at a time, so an agent can call start_recording without chronicle serve. chronicle mcp --no-record turns that off.

Packaged installs

Packaged installs need only uv.

claude plugin marketplace add aniketxdey/chronicle

claude plugin install chronicle@chronicle

gemini extensions install https://github.com/aniketxdey/chronicle

MCP Registry clients can search for io.github.aniketxdey/chronicle.

Hosted agents and APIs

Hosted agents need a public HTTPS URL. Anyone with the URL that these commands print can read your Chronicle data. Stop the tunnel when you finish.

export CHRONICLE_TOKEN=$(openssl rand -hex 16)

export CHRONICLE_PUBLIC_URL=https://YOUR-TUNNEL-HOST chronicle serve & cloudflared tunnel --url http://127.0.0.1:3030 echo "$CHRONICLE_PUBLIC_URL/mcp/$CHRONICLE_TOKEN"

chronicle mcp config prints a starting point for chatgpt, openai-api, anthropic-api, gemini-api, and http. Provider model names and beta flags change often, so check each provider's MCP documentation. The examples folder has longer scripts.

Files

The harness editor exports a .zip or one Markdown file. Each context file and workflow has Download .md. Each graph downloads as JSON, text, GraphML, or Cypher.

MCP tools

The server also has resources, such as chronicle://context/current, and two prompts: use_my_computer_context(task) and learn_from_recording(session_id). The MCP reference lists them all.

App, API, and CLI

chronicle serve runs the app at http://127.0.0.1:3030:

The REST API has interactive documentation at http://127.0.0.1:3030/docs. The CLI reference and REST reference list every command and route. The CLI has no harness commands.

Configuration

Chronicle reads these variables when a process starts. Settings in the app holds capture interval, idle threshold, screenshots, OCR, clipboard, redaction, and retention.

Models

A model is optional. Open Settings › Model, add a key, and press Use.

A key can also be in a .env file in ~/.chronicle or the current directory. A .env file never overrides a variable that is already set. Your choice in Settings overrides CHRONICLE_LLM, except CHRONICLE_LLM=off, which turns models off whatever Settings says.

Workflows, harness chat, and context file names use tool calls, so choose a model that supports them. Small local models often fail at these tasks.

Privacy

Recordings, screenshots, source items, and graphs stay in ~/.chronicle. Data leaves your computer in these cases:

• MCP clients: a connected agent receives the tool results it requests.
• Models: a cloud model receives window titles, URLs, system events, redacted screen text, and matching source items.
• Tunnels: anyone with your URL and token can read your data.
• Cloud sources: a provider sees the requests that Chronicle makes to it.

Redaction applies to text only. Screenshots keep whatever was on screen. [PRIVACY.md](https://github.com/aniketxdey/chronicle/blob/main/PRIVACY