ambient-context README

The project's README from github.com/dragthelake/ambient-context. As one markdown file: README.md.

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.

Download for macOS
Signed and notarised DMG. macOS 14 or later, Apple Silicon. Free and open source.

Ambient Context in use: the eye in the menu bar, the Overview window, and a processed day

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.

Overview: the eye on a CRT, a Record map of days marked Recorded or Processed, and a Notes list linking into processed days

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.

Notes tab: a written summary of the day with sessions, work and outcomes, each carrying its time range

Context tab, Websites: a table of the day's visits with domain, title, dwell time, visit count and first and last seen

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. Install the bundled skills from Settings and the agent also knows when to reach for them.

Agent tab: Claude Code connected, with separate Context and Notes model pickers and a daily schedule

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.

Privacy

The record is yours and it stays on your computer.

Context tab, Messages: captured blocks with their time, app, URL and body, each with Never record this app, Headings only for this site and Redact text like this buttons

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.

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

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.

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 (dragthelake/ambient-context)

Searching Database…

205 ·GitHub
Ambient-context
What is this?Ambient Context is a macOS menu bar app that silently records what you work on throughout the day and turns it into plain markdown files your AI assistant can use as context.
Does it record automatically, or do I have to type things in myself?It runs continuously in the background: while the menu bar icon is open, it reads the text of whichever window you have focused through the macOS accessibility tree every few seconds and appends it to the day's markdown file, with no manual input needed.
How do I install it and get going?Download the signed, notarised DMG from Releases, drag Ambient Context.app to Applications, open it, grant Accessibility access when asked, and pick a folder to store your records.
Do I need an agent CLI like Claude Code to get the daily summaries?Yes — turning the raw record into the Knowledge base and the day's Notes requires connecting an agent CLI you already have, such as Claude Code, Codex or opencode. Ambient Context itself never makes a model call.
Does it capture everything equally well?Chromium and Electron apps (Chrome, Slack, VS Code, Obsidian, Figma) are thin for the first few seconds of capture, and GPU-rendered terminals like Kitty or Alacritty expose little or no text at all, though Terminal.app and iTerm2 work fine.
Does it run on Intel Macs?No, it only runs on macOS 14 or later on Apple Silicon.
What are the three files it produces each day?Context is the raw timestamped record; Knowledge is six cited pages (People, Commitments, Threads, Products, Issues, Reading) built from it; Notes is a citation-checked daily write-up for standups or tomorrow's AI session.
How do I plug it into Claude Code or Cursor?Register the app's bundled binary as an MCP server in Claude Code, Claude Desktop, Cursor or Zed; it exposes twenty tools for reading days, searching the record, and reading the knowledge and notes.
Is it free to use?Yes, it's free and open source under MIT. The only ongoing cost is whatever agent CLI subscription you connect it to for processing days.
What are similar projects?WakeGPT, greenbubbles, solomd, tolaria, floral-notepaper, siyuan, note-gen, ai-manager
Which topics is it in?context, mcp-tools, personal-knowledge-management, menubar, menu-bar, privacy-tools, note-taking, tauri, accessibility, knowledge-base, apple-silicon, local-first
Creator
dragthelake
Size
47.7 MB
Stars
205
Updated
CommitOct 16Releasev1.1.4Oct 08
Age
1mo
Commits · 90 Days