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:
|
What it is |
Who it is for |
| Context |
The record. What was on screen, when, in which app, with the file path or URL where the app exposes one. |
Agents that need evidence. Grep. You, when you cannot remember which tab it was in. |
| Knowledge |
Six cited pages built from the record: People, Commitments, Threads, Products, Issues, Reading. Every claim points back to a block in the record. |
Agents building memory about your projects and the people in them. |
| Notes |
The day written up from the knowledge base, with citations checked against the record before it is saved. |
You, at the end of the day. Your standup. The model you open tomorrow morning. |
How it works
- 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.
- 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.
- 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. Install the bundled skills from
Settings and the agent also knows when to reach for them.
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
- The window opens by itself. Grant Accessibility when asked. This is the
permission that lets the app read window text; nothing works without it.
- Choose where to save. Prefer a folder outside iCloud Drive if you want
the files to stay on this computer only.
- Recording starts. Open eye: recording. Closed eye: not. Right-click the
icon for the folder and settings.
- 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.
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.
Settings > Agent skills installs five skills (catch me up, standup, weekly
review, tune rules, and the core loop they share) into ~/.claude/skills/
and ~/.agents/skills/, which Claude Code, Cursor, Codex, Zed, Copilot,
Gemini CLI, Goose and OpenCode all read. Details in
docs/skills.md.
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.
Ambient Context 是一款 macOS 菜单栏应用，会默默记录你一整天在忙什么，并把这些内容转换成纯 markdown 文件，供你的 AI 助手当作上下文使用。