Retrace

A private, on-device "rewind" for your Mac. Retrace quietly captures what's on
your screen, extracts the text and context, and lets you search and scrub back
through your day — plus time/usage analytics. Everything runs 100% on your
machine. No data ever leaves it. No accounts. No telemetry.

macOS only, on-device only. Retrace is built for macOS so it can lean on
native frameworks — ScreenCaptureKit, Accessibility, Vision, Foundation Models
(the on-device LLM), NaturalLanguage embeddings, SensitiveContentAnalysis, and
EventKit. There is no cloud component, by design.

The privacy promise (the whole point)

These are hard invariants, enforced in code and covered by tests — not preferences:

• Raw screenshots are never retained. Each frame goes to a private temp file,
  is processed (text + a small thumbnail), then deleted in a finally block —
  removed even if anything errors. Only extracted text, a short caption, a
  downscaled JPEG thumbnail, and metadata persist. (verified:
  tests/test_pipeline.py asserts the frame is gone on success, capture failure,
  and exceptions.)
• On-device only. No network calls for capture, OCR, captioning, embeddings, or
  search.
• Off by default. Capture is disabled until you turn it on, and that choice
  persists across restarts.
• Away = paused. When you're idle, the screen is locked, or the display is
  asleep, Retrace stops capturing and stops counting time — a machine left on and
  logged in never looks "active."
• Blocks what it shouldn't see. A password-manager denylist, incognito/private
  windows, and adult/sensitive content (URL/keyword rules and an on-device image
  scan) are all skipped before anything is stored.
• Hidden mode. One click pauses all recording (optionally for a set time).
• Bounded retention. Rows + thumbnails older than your window (default 30 days)
  are purged automatically, with a manual purge too.
• Local bind only. API and MCP listen on 127.0.0.1.
• No telemetry. Zero analytics, zero phone-home.

What you get

Screenshots

Now — the latest capture with an on-device caption, the now-playing track, and live CPU/memory:

Stats — time-by-app, weekly activity, and a CPU/memory chart (hand-rolled offline SVG):

Timeline — every captured moment, searchable, with expandable full text:

Search — one box, three modes (text · semantic · hybrid), with highlighted matches:

Screenshots use demo data. A short demo video lives in demo/ (Remotion).

Quickstart

Requires macOS 14+ (built/tested on macOS 26), the Xcode command-line tools
(swiftc), and uv.

make setup            # create the venv (Python 3.13) + install Retrace
make build-helpers    # compile the native Swift helpers into ~/.retrace/bin
uv run retrace init   # create ~/.retrace (config + database). Capture is OFF.
uv run retrace doctor # check permissions + capabilities

uv run retrace start    # enable capture
uv run retrace tick --force   # take one capture right now
uv run retrace serve    # open http://127.0.0.1:8765
uv run retrace menubar  # add the menu bar icon (starts the server if needed)

On a notched Mac with a crowded menu bar, the icon can hide behind the notch —
a menu bar manager (Ice / Bartender) or quitting a few menu bar apps reveals it.

The first capture triggers macOS permission prompts (Screen Recording,
Accessibility). retrace doctor tells you exactly what's missing and how to grant it.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│  Python core (FastAPI)                                            │
│   capture pipeline · daemon · activity · stats · search · plugins │
│   HTTP API + web UI  ·  read-only MCP server                      │
│        │  invokes (subprocess, JSON on stdout)                    │
│        ▼                                                          │
│  Swift helper binaries  (compile-on-first-use, cached in ~/.retrace/bin)
│   retrace-capture      ScreenCaptureKit frame + thumbnail (denylist excluded)
│   retrace-context      Accessibility: text / window / URL / doc / page text
│   retrace-ocr          Vision OCR fallback
│   retrace-present      idle / screen-lock / display-sleep + permission preflight
│   retrace-watch        NSWorkspace app-switch event stream (event-driven capture)
│   retrace-embed        NaturalLanguage sentence embedding
│   retrace-caption      Foundation Models text → 1-2 sentence caption
│   retrace-sensitivity  SensitiveContentAnalysis adult/NSFW image scan
└──────────────────────────────────────────────────────────────────┘
        All data under ~/.retrace  (SQLite + thumbnails). knowledgeC /
        Safari / Chrome history are read directly for time analytics.

The capture cycle: gate (enabled / present / hidden) → context (app, window,
URL, text) → privacy (denylist / incognito / sensitive) → dedup → frame +
thumbnail → on-device sensitivity scan → text (Accessibility, else OCR) →
caption → embed → persist → delete the raw frame, always.

Permissions

retrace doctor reports each of these; Retrace degrades gracefully when one is missing.

For full-page text capture, also enable "Allow JavaScript from Apple Events" in your
browser (Safari: Develop menu; Chrome: View → Developer).

Privacy controls

• Hidden mode — the 🙈 Hidden mode button (or POST /capture/pause?minutes=N)
  stops all recording until you resume.
• Away handling — "Pause when away" (on by default) plus an adjustable idle
  threshold; the header shows ◌ AWAY / ◍ LOCKED / ◍ DISPLAY OFF.
• Sensitive content — two layers, both on by default: an editable
  domain/keyword blocklist, and an on-device SensitiveContentAnalysis image scan
  that drops flagged frames (activates once you enable "Sensitive Content Warning" in
  System Settings).
• Incognito — Chrome-family private windows are detected and never captured.
• Denylist — password managers and other apps you list are never captured (and
  are natively excluded from the frame via ScreenCaptureKit).

App plugins

Plugins extend Retrace per-app. A plugin can enrich a capture (when a matching
app is frontmost), collect an app's own data on a schedule, and/or poll for
lightweight periodic sampling (every ~capture interval). Built-ins cover Claude Code
transcripts, Spotify + Apple Music now-playing, system CPU/memory, calendar (EventKit),
macOS notifications, git commits across your repos, Apple Mail subjects, browser
downloads, recently-opened files, clipboard, and shell history — all on-device.

# ~/.retrace/plugins/my_app.py
from retrace.plugins import RetracePlugin

class MyApp(RetracePlugin):
    name = "my-app"
    bundle_ids = ("com.example.myapp",)

    def enrich(self, context, settings):
        return {"caption": "Doing the thing in MyApp", "text_append": "extra context"}

    def collect(self, settings):
        # read the app's data store, write captures, return a summary
        return {"name": self.name, "ingested": 0}

PLUGIN = MyApp()

Run collectors with uv run retrace collect (also runs daily in the daemon, and from
the Settings → "Collect app history" button). The built-in Claude Code plugin
ingests ~/.claude/projects/*.jsonl session transcripts into your timeline, fully
searchable.

MCP (read-only)

Other agents can query Retrace over MCP. It exposes only read/search tools — no
start/stop, no purge, no config changes:

retrace_search · retrace_timeline · retrace_get_capture ·
retrace_what_was_i_doing · retrace_stats · retrace_now · retrace_list_apps

Register it (e.g. in claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "retrace": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/retrace", "retrace", "mcp"]
    }
  }
}

HTTP API

Bound to 127.0.0.1. Highlights:

• GET /capture/status · POST /capture/start|stop|tick|pause|resume
• GET /capture/recent · GET /capture/{id} · GET /capture/{id}/image · GET /capture/{id}/html
• POST /capture/purge?days=
• GET /search?q=&mode=text|semantic|hybrid
• POST /activity/scan · GET /activity/apps|domains|status
• GET /stats/daily|weekly|top
• GET /permissions · GET|POST /config · GET /plugins · POST /plugins/collect

Configuration

~/.retrace/config.toml (env vars RETRACE_* override it; both override defaults).
Edit the common ones in the Settings panel. Keys include: capture_interval_s,
dedup_window_s, idle_threshold_s, pause_when_away, retention_days,
thumb_max_edge, enable_semantic_search, enable_caption, denylist_bundle_ids,
capture_private_browsing, block_sensitive_content, block_sensitive_images,
sensitive_domains, sensitive_keywords, capture_page_text, capture_page_html,
enable_plugins, disabled_plugins.

Run it in the background

A launchd user-agent template lives at scripts/com.retrace.daemon.plist (edit the
two absolute paths, then launchctl load -w ~/Library/LaunchAgents/...). See the
comments in that file for install/uninstall.

Development

make test            # run the test suite (isolated temp DB; never touches ~/.retrace)
make build-helpers   # (re)compile the Swift helpers
make run             # retrace serve

Tests use a throwaway RETRACE_HOME and refuse to run against your real database.
Native helpers are stubbed by default so the suite is fast and needs no Swift toolchain.

Screenshots of the UI live in docs/screenshots/.

License

Apache-2.0. Built only on third-party + Apple frameworks. No telemetry,
ever.