Install

Chronicle is one Python package, chronicle-context, with a chronicle command. These steps install it, check what your machine can capture, and make a first recording.

1. Install uv and Chronicle

Chronicle needs Python 3.10 or newer. uv installs it in its own environment and is also what the packaged plugins use to start the server.

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install "chronicle-context[graph]"

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install "chronicle-context[graph]"

If you prefer pipx: pipx install "chronicle-context[graph]". The extras are optional:

Extra	Adds	Why
`graph`	scikit-learn, scipy, numpy	Better merging of near-duplicate graph nodes
`llm`	openai, python-dotenv	Model refinement of the graph and written context files (needs an OpenAI key)

Without extras, the only dependencies are FastAPI and uvicorn.

2. Try the sample workday

This works on every platform and records nothing.

chronicle demo
chronicle graph show
chronicle context "finish the Acme export"

3. Set up capture

Grant Screen Recording and Accessibility under System Settings › Privacy & Security to whatever runs Chronicle. That's your terminal for chronicle record and chronicle serve, or the MCP host app (Claude Desktop, Cursor, and so on) when the agent starts recording itself.

Browser URLs need a one-time Automation prompt per browser. Chronicle reads tabs from Safari, Chrome, Arc, Brave, Edge, Vivaldi, and Opera. Screen text comes from the Accessibility tree, with OCR as a fallback for apps that expose no text:

brew install tesseract   # optional OCR

Linux capture works on X11 and is best effort. Install the tools for what you want recorded:

sudo apt install xdotool x11-utils     # window and title (xdotool, xprop): required
sudo apt install scrot                 # screenshots; grim, gnome-screenshot, or ImageMagick import also work
sudo apt install xclip xprintidle      # clipboard (or wl-paste) and idle time
sudo apt install tesseract-ocr         # screen text

On Linux, screen text comes only from OCR, and browser URLs are not read.

Windows capture is best effort. Chronicle reads the front window, idle time, screenshots, and the clipboard through user32 and PowerShell, with no extra setup.

Screen text comes only from OCR, so install Tesseract and put tesseract on your PATH. Browser URLs are not read on Windows.

Then check what this machine can capture:

chronicle doctor

4. Record

chronicle record 30m --label "expense report"   # durations like 90s, 15m, 2h, 1h30m
chronicle serve                                 # or use the web UI at http://127.0.0.1:3030

When a recording ends, Chronicle rebuilds its graph shard (and runs model refinement if an OpenAI key is set). Check what an agent would see with chronicle context --session 1, then connect an agent.

Optional: model refinement

Without a key, Chronicle runs fully offline. With one, a model types and links graph nodes and writes the context files. It sends window titles, URLs, and redacted screen text to OpenAI.

uv tool install "chronicle-context[graph,llm]"
echo "OPENAI_API_KEY=sk-..." >> ~/.chronicle/.env

uv tool install "chronicle-context[graph,llm]"
Add-Content "$HOME\.chronicle\.env" "OPENAI_API_KEY=sk-..."

Set CHRONICLE_LLM=off or use Settings › LLM refinement to turn it off. OPENAI_BASE_URL points it at any OpenAI-compatible server, such as Ollama.

Updating and uninstalling

uv tool upgrade chronicle-context
uv tool uninstall chronicle-context

Uninstalling leaves your data in ~/.chronicle (or CHRONICLE_HOME). Delete that folder to remove every recording, screenshot, and graph.