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
Что это?Ambient Context — приложение для строки меню macOS, которое незаметно записывает, над чем вы работаете в течение дня, и превращает это в простые markdown-файлы, которые ваш ИИ-ассистент может использовать как контекст.
Он записывает автоматически или мне нужно вводить всё самому?Он постоянно работает в фоне: пока открыта иконка в строке меню, каждые несколько секунд он читает через дерево доступности macOS текст окна, находящегося в фокусе, и дописывает его в markdown-файл дня — без какого-либо ручного ввода.
Как его установить и начать пользоваться?Скачайте подписанный, нотаризованный DMG из Releases, перетащите Ambient Context.app в Applications, откройте его, когда будет запрошено, выдайте доступ к Accessibility и выберите папку для хранения записей.
Нужен ли мне агентский CLI вроде Claude Code для получения ежедневных сводок?Да — чтобы превратить сырую запись в базу Knowledge и заметки Notes за день, нужно подключить уже имеющийся у вас агентский CLI, например Claude Code, Codex или opencode. Сам Ambient Context никогда не обращается к модели.
Одинаково ли хорошо он захватывает всё?В приложениях на Chromium и Electron (Chrome, Slack, VS Code, Obsidian, Figma) первые секунды захвата текста мало, а GPU-рендеренные терминалы вроде Kitty или Alacritty отдают мало текста или не отдают вовсе; Terminal.app и iTerm2 при этом работают нормально.
Работает ли он на Mac с Intel?Нет, только на macOS 14 или новее на Apple Silicon.
Какие три файла он создаёт каждый день?Context — сырая запись с отметками времени; Knowledge — шесть страниц со ссылками на источники (People, Commitments, Threads, Products, Issues, Reading), построенная на её основе; Notes — выверенная по цитатам ежедневная сводка для стендапов или завтрашней сессии с ИИ.
Как подключить его к Claude Code или Cursor?Зарегистрируйте поставляемый с приложением бинарник как MCP-сервер в Claude Code, Claude Desktop, Cursor или Zed; он предоставляет двадцать инструментов для чтения дней, поиска по записи и чтения базы знаний и заметок.
Это бесплатно?Да, это бесплатно и open source под лицензией MIT. Единственная постоянная трата — подписка на тот агентский CLI, который вы подключите для обработки записей.
What are similar projects?WakeGPT, greenbubbles, solomd, tolaria, floral-notepaper, note-gen, siyuan, 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 17Releasev1.1.5Oct 17
Age
1mo
Commits · 90 Days