Ambient Context

Ambient Context writes down what you work on during the day to give your
AI assistant better context.

A macOS menu bar app that keeps a written record of what you work on, in
plain markdown, in a folder you own. Point Claude Code, Cursor, Codex or
any MCP client at your context folder.

_{Signed and notarised DMG. macOS 14 or later, Apple Silicon. Free and open source.}

The problem

You spend the day reading, writing, replying and deciding. None of it
reaches the AI assistant you open at 4pm. So you paste in the email, explain
the ticket, summarise the call, and the model still works from a fraction
of what you actually saw. The context existed. It was on your screen. Nobody
wrote it down.

What Ambient Context does

While the eye in your menu bar is open, the app reads the text of whichever
window you have focused (through the macOS accessibility tree, every few
seconds) and appends it to markdown files for the day. At a time you
choose, or when you press the button, an agent you already have turns that
record into two more things: a small cited knowledge base and a written
summary of the day.

Three files per day, each one useful on its own:

How it works

1. Record. Grant Accessibility, choose a folder, and the eye opens.
   Capture starts with the app from then on. Click the eye to stop;
   stopping is remembered until you start again.
2. Process. Connect an agent CLI you already have (Claude Code, Codex or
   opencode). Set a time, or press Process day. The agent reads the record
   and writes the knowledge and the notes. It runs on your machine under
   your own subscription; Ambient Context never makes a model call itself.
3. Ask. Register the app as an MCP server in Claude Code, Claude
   Desktop, Cursor or Zed, or just point an agent at the folder. Twenty
   tools cover reading days, searching the record, reading the knowledge
   and notes, and controlling capture.

With Claude Code you can send the long input (the day's record) to a
cheaper Context model and reserve a stronger Notes model for the page you
will actually read.

Why the record is worth reading

Raw screen text is noisy. Ambient Context is built so an LLM can read it
cheaply.

• Deduplicated across the day. A page you keep coming back to is
  recorded once, not once per poll.
• Interface junk filtered. View counts, "8 minutes ago", media player
  positions and navigation menus are dropped. On two real days of capture
  this removed about a fifth of the lines without losing content.
• Real references, not scraped fragments. Blocks record the document
  path or URL where the app exposes one, so a reader can open the actual
  file instead of trusting the excerpt.
• Mail and chat go to their own file. Messages are routed to
  messages.md so the timeline stays readable and message bodies are easy
  to exclude from a prompt.
• An AGENTS.md in the folder explains the format to whatever reads it.

Privacy

The record is yours and it stays on your computer.

• No screenshots, no video, no OCR. Text only, from the accessibility
  API, and only from the focused window. Never while the screen is locked.
• No account, no server, no telemetry. The app does not upload your
  record. The optional update check reaches GitHub Releases and nothing
  else.
• Files you own. Plain markdown in a folder you chose. Move them, grep
  them, delete them.
• Defence in depth before writing. Secure password fields are skipped
  at the source. Password managers and private browsing windows are never
  recorded. Credential, API-key and card-shaped strings are scrubbed to
  [redacted]. These are heuristics, not a guarantee, so treat the folder
  as sensitive.
• Rules you set from the record itself. Every block in the Context tab
  offers Never record this app, Headings only for this site, and Redact
  text like this, so you can tighten capture the moment you see something
  you would rather not keep.
• Boundaries you choose are named as such. An agent CLI you connect and
  a synced folder (iCloud, Dropbox) are separate trust decisions. The app
  warns if the folder you pick is inside iCloud Drive.

The trust boundary, data inventory, claims matrix and known gaps are in
Privacy and security.

Install

Requires macOS 14 or later on Apple Silicon.

Download the signed, notarised DMG from
Releases,
drag Ambient Context.app to Applications and open it.

To build it yourself you need Node,
Rust and the Xcode Command Line Tools:

git clone https://github.com/dragthelake/ambient-context
cd ambient-context
npm install
npm run tauri build

The app lands in src-tauri/target/release/bundle/macos/. For development,
npm run tauri dev runs it with hot reload.

First run

1. The window opens by itself. Grant Accessibility when asked. This is the
   permission that lets the app read window text; nothing works without it.
2. Choose where to save. Prefer a folder outside iCloud Drive if you want
   the files to stay on this computer only.
3. Recording starts. Open eye: recording. Closed eye: not. Right-click the
   icon for the folder and settings.
4. To get Knowledge and Notes, open the Agent tab, pick an agent CLI, and
   set the time you want each day processed. Or open any recorded day and
   press Process day.

Connect your tools

The app binary is also an MCP server. For Claude Code:

claude mcp add --scope user --transport stdio ambient-context -- "/Applications/Ambient Context.app/Contents/MacOS/ambient-context" mcp

Claude Desktop, Cursor, Zed and generic stdio clients are covered in
docs/mcp.md. Read tools work whether or not the app is
running. Anything that changes state goes through the running app, so
every write lands in the day's ledger with your client's name on it.

What a day looks like

Days/2026-09-04/
  apps.md        the timeline, with native app bodies
  websites.md    a table of visits, without page bodies
  messages.md    mail and chat bodies, routed here
KB/2026-09-04/
  people.md  commitments.md  threads.md  products.md  issues.md  reading.md
  manifest.md
Summaries/2026-09-04.md
AGENTS.md

Known limits

• Chromium and Electron apps (Chrome, Slack, VS Code, Obsidian, Figma)
  build their accessibility tree on first contact, so the first seconds of
  capture in those apps are thin and fill in on later passes. Chrome may
  show a slightly glitchy window-resize animation while enabled.
• GPU-rendered terminals (Kitty, Alacritty) expose little or no text.
  Terminal.app and iTerm2 work.
• If an app comes back empty or thin, open an
  issue with the
  app name and what you were doing in it. docs/bug-reports.md
  says what to include and what to leave out.

Tests

cd src-tauri && cargo test
cd .. && npx tsc --noEmit && npx vitest run

Support the project

Ambient Context is free, open source and built by one person. If it earns
a place in your menu bar, three things help: star the repo, report the apps
that come back thin, and if you want to, buy me a
coffee.

Licence

MIT. The bundled Funnel fonts carry their SIL OFL text. See
CHANGELOG.md for what is in each release.