Chronicle

Local-first developer observability for macOS
Remember what you were doing — across apps, repos, and terminals — without sending data to the cloud.

---

Overview

Chronicle runs a background daemon that records structured activity — window focus, git operations, terminal commands, and meaningful file changes — into a local SQLite database. Browse timelines in a Tauri + Svelte desktop app, search your history, or query recent work from AI tools via MCP.

Private	Data stays in ~/.chronicle/ — no account, no telemetry
Project-aware	Events grouped by git/Cargo roots
AI-ready	chronicle-mcp for Cursor, Claude Desktop, and other MCP clients
macOS-native	Collectors use FSEvents, git reflogs, and lsappinfo (no Accessibility prompt)

---

Architecture

flowchart TB
  subgraph sources["Signal sources"]
    WF["Window focus"]
    GIT["Git reflogs"]
    FS["Filesystem"]
    SH["Shell hook"]
    HTTP["HTTP ingress"]
  end

  subgraph daemon["chronicle-daemon"]
    COL["Collectors"]
    FILT["Filter + label"]
    SPAN["Span processor"]
    IPC["Unix socket IPC"]
  end

  subgraph persistence["chronicle-store"]
    DB[("SQLite + FTS5<br/>~/.chronicle/chronicle.db")]
  end

  subgraph clients["Clients"]
    UI["Tauri desktop app"]
    MCP["chronicle-mcp"]
    CLI["CLI / extensions"]
  end

  sources --> COL
  COL --> FILT --> SPAN --> DB
  FILT --> IPC
  IPC <--> UI
  IPC <--> MCP
  IPC <--> CLI

Loading

Crate / binary	Role
chronicle-core	Event schema, spans, sessions
chronicle-store	SQLite persistence and FTS search
chronicle-ipc	Length-prefixed JSON over Unix domain socket
chronicle-daemon	Collectors, filtering, launchd service
chronicle-mcp	MCP tools for AI assistants
src-tauri + src/	Desktop UI (Svelte 5)

Deep dive: Documentation · start with Introduction

---

Install

macOS (recommended)

Signed, notarized DMGs are on GitHub Releases:

1. Download arm64 (Apple Silicon) or x64 (Intel)
2. Drag Chronicle to Applications
3. Launch — the background service starts automatically
4. Optional: Settings → Install shell hook for terminal capture

Build from source

git clone https://github.com/aeswibon/chronicle.git
cd chronicle
bun install
cargo build --release -p chronicle-daemon -p chronicle-mcp

./target/release/chronicle-daemon install --watch ~/Developer
bun run tauri dev

Configure watch directories in Settings or ~/.chronicle/config.toml.

Homebrew

Homebrew looks for homebrew-chronicle by default — tap this app repo explicitly:

brew tap aeswibon/chronicle https://github.com/aeswibon/chronicle
brew trust aeswibon/chronicle
brew install --cask chronicle

The cask quits and replaces an existing Chronicle.app (including a prior DMG install) so you do not need --force.

Upgrade (Homebrew does not include casks in plain brew upgrade):

brew update
brew upgrade --cask chronicle

If you installed from a DMG instead of the tap, Homebrew will not list Chronicle in brew outdated --cask — use brew install --cask chronicle to switch to the tap, or download the latest DMG from Releases.

Checksum errors after a release usually mean a stale download cache:

brew update
brew cleanup --prune=1
brew install --cask chronicle

The cask lives in Casks/chronicle.rb (not Formula/).

---

Features

Area	What Chronicle captures
Timeline	Chronological activity with labels and highlights
Projects	Per-repo views, sorted by last activity
Sessions	Rule-based daily rollups; optional AI summaries
Search	FTS over events, projects, and metadata
MCP	search_events, get_timeline, list_projects, get_project_context, …
Privacy	Collector toggles, retention prune, shell secret redaction

Collectors can be disabled individually in Settings. See the capture pipeline for details.

---

MCP setup

Register chronicle-mcp in your MCP client (daemon must be running):

{
  "chronicle": {
    "command": "/path/to/chronicle-mcp",
    "args": []
  }
}

---

Platform support

Component	macOS	Linux / Windows
Daemon + SQLite + IPC	✓	✓
Shell / git / filesystem collectors	✓	Partial
Window focus collector	✓	—
Tauri desktop UI	✓	Build from source
launchd auto-start	✓	Manual chronicle-daemon start

---

Privacy

Chronicle does not record keystrokes, clipboard, screenshots, audio, or video. It does record app names, window titles, shell commands, git messages, and file paths (not file contents). Everything stays on disk unless you add sync yourself.

→ Privacy details

---

Development

cargo test --workspace
bun run check

→ Clients and development · Contributing collectors

---

Documentation

Guide	Topic
Introduction	What Chronicle is and who it's for
System design	Processes, crates, deployment
Capture pipeline	Collectors, filtering, spans
Storage and query	Schema, FTS, query APIs
Clients and development	IPC, MCP, UI, contributing
External plugins	IDE and browser extensions
macOS release signing	Signed DMGs and CI setup

---

License

MIT