Mosaic

Understand and improve your productivity

Mosaic turns your raw computer activity into a nightly narrative, real projects and tasks, a deterministic focus score, and one honest nudge for tomorrow. Completely open source. Uses your claude code subscription.

What is Mosaic?

Most time trackers hand you a messy activity log. Mosaic reads that log (via ActivityWatch) and, once a night, an LLM coach makes sense of it: it writes a short narrative of how the day went, reconstructs the real projects and tasks you worked on, scores your focus from the timeline (in code, not by vibes), judges the day against the plan you set, and commits to one concrete change for tomorrow. A weekly review picks one change for next week.

Why Mosaic?

• See where your time actually goes — not app names, but "you shipped the risks prototype, then lost 90 minutes context-switching between Slack and review."
• Accountability that sticks — state a plan; the coach checks whether you kept yesterday's one recommendation before making the next.
• Focus you can trust — the focus score is computed from your timeline and fully explainable, and it discounts window-switching while your agents run (orchestration ≠ distraction).

Built for deep-work knowledge workers, freelancers who need to know where the hours went, and founders calibrating how their focus shifts week to week.

How it compares

	Mosaic	DoneThat	ActivityWatch	Rewind
Open source	✅	app only	✅	❌
100% local capture	✅	✅	✅	✅ (encrypted)
LLM day/week coaching	✅	✅	❌	partial
Bring-your-own LLM	✅	✅	—	❌
Self-hosted, no account	✅	❌ (service)	✅	❌
Price	free	paid	free	paid

Screens

Features

• Day plans & one-recommendation commitments — state priorities; the coach scores the day against them and commits to a single checkable action, then judges whether you kept it.
• Nightly narrative + project/task reconstruction — a readable summary of how the day went and what you actually built, cross-referenced with your coding-agent sessions.
• Deterministic focus score — computed from the timeline, with explainable components; orchestration-aware.
• Weekly review — reviews the last 7 days and proposes one structural change.
• Automation backlog — repeated workflows the coach spots persist across days; it can draft a real script for review (never executed automatically).
• Reflect — a nightly read on how you work with Claude Code itself: task-type mix, autonomy ratio, tool usage, model mix, scored across delegation, description, discernment, and diligence. Prompt excerpts are secret-redacted and, by default, only sent to providers that keep them on your machine or your own subscription (claude_code, ollama) — toggle or disable entirely in Settings.
• Midday nudge — a desktop notification comparing hours-so-far against today's plan.
• Screenshot capture + OCR and custom metrics (mood, pushups, …) onto the same local timeline.
• A configurable dashboard — movable/resizable panels, editable coaching prompts, theming, and a Settings tab that edits everything (including the privacy filter).

Quick start

git clone https://github.com/F3dai/mosaic ~/Projects/mosaic
cd ~/Projects/mosaic
make install

make install is idempotent and does everything: installs backend + frontend dependencies, builds the dashboard, scaffolds ~/.config/mosaic, asks which LLM provider to use, signs you into your Claude subscription (claude auth login) if you pick claude_code, installs and starts the background services, and finishes with a mosaic doctor health check. Open http://127.0.0.1:6969 when it's done.

Prerequisites it can't install for you (they need your package manager):

curl -LsSf https://astral.sh/uv/install.sh | sh                       # uv (both platforms)

# Linux (Arch)
sudo pacman -S nodejs npm activitywatch grim tesseract tesseract-data-eng
yay -S aw-awatcher                                                     # Wayland window+AFK watcher

# macOS
brew install node tesseract
brew install --cask activitywatch                                     # bundles aw-server + watchers

Test it first, safely: make install-test runs the whole flow against a throwaway config dir with the mock provider and no services — it never touches your real setup.

Platform notes: on Linux, make install installs the Mosaic systemd user units (the ActivityWatch units are machine-specific — see systemd/README.md). On macOS, install the LaunchAgents from launchd/README.md and grant the Screen Recording permission. Prefer manual? cd backend && uv sync, cd frontend && npm install && npm run build, uv run mosaic init.

Architecture

flowchart LR
  AW["aw-awatcher · aw-watcher-web<br/>mosaic capture (screen+OCR)<br/>custom metrics"] --> S["aw-server<br/>127.0.0.1:5600"]
  S --> P["aggregate → redact → focus score → LLM"]
  P --> DB["SQLite + markdown exports<br/>~/.local/share/mosaic"]
  P --> API["FastAPI 127.0.0.1:6969<br/>+ built React SPA"]
  DB --> API
  API --> UI["Dashboard (browser)"]

Loading

• backend/src/mosaic/ — aw/ (AW read + AQL), capture/ (screen+OCR), coaching/ (aggregate, redaction, scoring, provider-agnostic LLM, prompts, pipeline, automate), store/ (SQLite + markdown), api/ (FastAPI + SPA serving)
• frontend/ — Vite + React + TS dashboard (built once, served by the backend)
• systemd/ (Linux units) · launchd/ (macOS agents)

Configuration

Mosaic works with zero config — every default is baked in. To tune capture intervals, toggle sources, adjust the focus score, change the nudge time, or pick an LLM provider from a file, drop an optional ~/.config/mosaic/config.toml (template: config/config.toml.example) — or just use the dashboard's Settings tab, which edits the same file. Precedence is code default < config.toml < env.

LLM provider (MOSAIC_LLM_PROVIDER, default claude_code):

Provider	What it uses	Needs
claude_code	headless claude -p via your Claude subscription	claude CLI, signed in (claude auth login)
openrouter	OpenAI-compatible cloud API	OPENROUTER_API_KEY
ollama	local qwen3:8b — zero cloud egress	Ollama running
mock	canned output for tests/dev	nothing

Full reference — every key, the Settings UI, prompt overrides, and the experimental audio/webcam stubs — in docs/configuration.md.

Daily use

The dashboard is at http://127.0.0.1:6969. Timers run the evening coach (23:30), the Reflect run (23:45), midday nudge (13:00), and weekly review (Sun 18:00). Everything is also on the CLI:

mosaic doctor                                   # health checklist
mosaic plan set "ship risks proto; 2 emails"    # today's priorities
mosaic coach run [--horizon day|week] [--provider ...] [--dry-run]
mosaic reflect run [--date today] [--provider ...] [--dry-run]  # AI-collaboration reflection
mosaic reflect show [--date ...]                # print a stored reflection
mosaic nudge                                    # midday check-in now
mosaic automate list [--all] | build <key> | dismiss <key>
mosaic rollup [--days 30]                        # recompute stats/trends rollups
mosaic metric define mood --type scale --min 1 --max 5 --prompt "Mood?"
mosaic serve [--port 6969]                       # run the backend in the foreground

mosaic coach run --dry-run prints the redacted DayContext that would be sent — no LLM call.

Privacy

Mosaic is a personal surveillance tool for an audience of one — you. Its design reflects that:

• Everything binds to localhost (AW 5600, backend 6969, Ollama 11434). Nothing listens on the network; AW has no auth, so localhost-only is the boundary — never bind 0.0.0.0.
• Capture + storage never leave the machine. Screenshots and OCR text stay under ~/.local/share/mosaic/.
• The coaching call is the only egress, and it sends a redacted, aggregated summary — never raw events — to the provider you chose. Choose ollama or claude_code for zero third-party egress.
• Redaction is the chokepoint. ~/.config/mosaic/redaction.toml (apps, title_regex, url_domains; drop or mask) is applied after aggregation, before any prompt or network call. If the file is absent, redaction is off and Mosaic warns — toggle and edit it from the Settings tab. Verify with mosaic coach run --dry-run.
• No account, no telemetry. Secrets live only in ~/.config/mosaic/mosaic.env (chmod 600), never in the repo. Automation scripts are written for review, never executed by Mosaic.
• Reflect reads your own Claude Code transcripts (~/.claude/projects) for metrics and, optionally, redacted prompt excerpts. It runs the same secret-redaction pass as everything else, defaults prompt excerpts to claude_code/ollama only (prompt_text_local_only in config), and can be turned off entirely (reflect.enabled = false).

See SECURITY.md for the full threat model and how to report issues.

Data locations

What	Where
ActivityWatch DB	~/.local/share/activitywatch/
Mosaic DB (runs incl. Reflect, plans, commitments, backlog, rollups, metrics)	~/.local/share/mosaic/mosaic.db
Markdown exports · LLM traces · screenshots · drafted scripts	~/.local/share/mosaic/{exports,llm,screenshots,automations}/
Config + secrets	~/.config/mosaic/{config.toml,mosaic.env,redaction.toml}

Contributing

Issues and PRs welcome. make test runs the backend suite; make verify seeds synthetic data and runs a mock coaching pass end-to-end; CI runs ruff + pytest + the frontend build on every PR. Please don't add data sources or network egress without discussion — the local-first, minimal-egress posture is the point.

License

MIT © 2026 F3dai