Docs

01Getting started

Earlyn needs macOS 14 or later · Apple Silicon.

1. Download Earlyn, drag it to Applications and open it. It appears in the menu bar, not the Dock.
2. Follow the setup. Earlyn asks for Screen Recording, Accessibility, the microphone and notifications, each with what it is for, and relaunches once after Screen Recording.
3. Turn Recording on from the menu bar. Earlyn never starts recording by itself; it is always your call.
4. Press ⇧⌥Space to search or ask. Open Rewind from the menu bar to scroll back through time.

Useful first stops in Settings: Privacy to exclude apps (password managers, banking), Memory to pick the model (Apple on-device, or Earlyn's own model as a one-time download) and set up workflows, and Storage to see disk use or delete the last hour or everything.

02Permissions

Each permission is asked for when it is needed, and each one stays on your Mac.

Screen Recording

Required. Lets Earlyn see the screen and window titles. macOS asks you to relaunch after granting it, and macOS 15+ periodically asks you to confirm it again; that prompt comes from the system.

Accessibility

Strongly recommended. Earlyn reads exact text from apps and the address of the current browser tab, instead of falling back to OCR. It never reads password fields.

Microphone and Speech Recognition

Only for meetings. Asked the first time you press Record meeting. Speech is recognised on device only.

You can change any of them in System Settings → Privacy & Security.

03Connecting Claude Code

The easy way: Earlyn → Settings → Connect → Claude Code → Connect. Earlyn turns on the local API and registers its MCP bridge for you. Restart Claude Code once. By hand:

claude mcp add --scope user earlyn -- "/Applications/Earlyn.app/Contents/MacOS/earlyn-mcp"

The bridge is a small stdio program inside the app. It talks to Earlyn over 127.0.0.1 with the token from api.json. Local API and MCP are part of Pro (and the trial).

04Connecting Codex

Settings → Connect → Codex → Connect adds the server for you. To do it by hand, add this to ~/.codex/config.toml:

[mcp_servers.earlyn]
command = "/Applications/Earlyn.app/Contents/MacOS/earlyn-mcp"

Any other MCP client works the same way: point it at the bridge as a stdio server.

05Local API

Turned on in Settings → Connect. Earlyn listens on 127.0.0.1:17370 (the next free port if that one is taken) and nowhere else. Every request needs the bearer token stored, with the port, in:

~/Library/Application Support/Earlyn/api.json

TOKEN=$(jq -r .token ~/Library/Application\ Support/Earlyn/api.json)
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:17370/v1/search?q=invoice&limit=10"

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"question": "what did I work on yesterday?"}' \
  http://127.0.0.1:17370/v1/ask

search and recent accept from, to (ISO 8601), app (a bundle id from /v1/apps) and limit. POST /v1/sql takes {"sql": "SELECT …"} and only runs read-only statements; the same console lives in Settings → Connect → Advanced. Export (JSON Lines, plain files) is in the same tab.

06Command line

Earlyn ships with an earlyn command. Install it once in Settings → Connect → Command line (macOS asks for your password to add it to /usr/local/bin), then open a new Terminal window. It talks to the local API, so turn that on or connect an AI tool first.

earlyn search "pricing table"
earlyn search invoice --app Mail --limit 5
earlyn ask "what did we decide about the launch date?"
earlyn recent --minutes 60
earlyn context --minutes 30 | pbcopy        # the last half hour, ready to paste
earlyn memory 1842
earlyn meetings --limit 3
earlyn search acme --json | jq '.[].title'

earlyn context is the quickest way to give an AI tool what you were just doing: pipe it to pbcopy, or run it from inside Claude Code or Codex. Everything runs on this Mac through 127.0.0.1.

07Live events & SDK

GET /v1/stream keeps the connection open and sends Server-Sent Events as they happen: screen (a new moment: app, window, URL and the first 2000 characters of its text), transcript (a spoken line), meeting (started or ended) and agent (a run and its output). Pick some with ?types=transcript,meeting. A comment line arrives every 15 seconds; at most eight streams at once. Nothing is produced while nobody listens.

earlyn watch                                   # everything, readable
earlyn watch --types transcript --json | jq .text

curl -N -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:17370/v1/stream?types=screen"

The TypeScript SDK (sdk/js in the app's repository, no dependencies, Node 18+ or Bun) finds the port and token itself and wraps every route:

import { Earlyn } from "@earlyn/sdk";

const earlyn = new Earlyn();
const hits = await earlyn.search("pricing table", { limit: 10 });
const { answer } = await earlyn.ask("what did we decide about the launch?");

for await (const event of earlyn.events({ types: ["transcript", "meeting"] })) {
  if (event.type === "transcript") console.log(event.speaker, event.text);
}

08Plugins

A plugin is a folder with a plugin.md and a program. An agent whose Send to is that plugin hands it its output when it runs. Install plugins in Settings → Automation → Plugins, or get one from the gallery.

---
name: Say it
description: Reads the first lines of the output aloud.
run: main.sh
timeout: 60
---

• The program gets JSON on stdin: agent, trigger, title, output and period (from, to). Its first 300 characters of output show in the agent's run steps; a non-zero exit marks the run failed.
• It runs in its own folder with EARLYN_PLUGIN_DIR, and EARLYN_API_URL / EARLYN_API_TOKEN when the local API is on, so it can search your memory too. It is stopped after timeout seconds (at most 300).
• Earlyn runs a plugin only after you have read and approved it. The approval is pinned to the files' SHA-256: change a byte and it asks again.
• An agent.md next to plugin.md is added to your agents (turned off) when you install the plugin. In an agent file, write send_to: plugin:say-it.

09MCP tools

What Claude Code, Codex and other MCP clients can call once connected:

• search_memoryFull-text search over everything you saw or heard
• recent_memoriesThe newest memories, optionally by app
• get_memoryOne memory with its full text and context
• get_frameThe screenshot behind a memory
• list_appsApps Earlyn has seen
• list_meetingsRecorded meetings
• get_meetingTranscript, summary, decisions and action items
• daily_digestsDaily digests of your days
• user_profileProfile notes you allowed Earlyn to keep
• ask_earlynAsk a question, answered on-device with references
• query_sqlRead-only SQL for anything the tools do not cover
• list_skillsSkills written from your own work
• get_skillOne skill as SKILL.md
• run_workflowRun a workflow now
• workflow_outputsLatest workflow results
• memory_statsHow much Earlyn remembers, and since when
• custom_*Your own prompt-tools, one MCP tool each

Custom tools are made in Settings → Connect → Custom tools: a name, a description the AI sees, and a prompt Earlyn runs over your memories. Each appears as custom_…. Clients see changes after they reconnect.

10License keys

Buying Pro puts a license key in your account (and sends it by e-mail). It is one line starting with EARLYN-. Paste it in Earlyn → Settings → Plan and press Activate.

Keys are signed. Earlyn checks the signature on your Mac, so activation works offline and never contacts a server. Lost your key? It is always in your account.