# Egg — alpha

Egg is a local-first library for the visual things you save. Everything you
put in it is scanned once by Claude into a searchable record — description,
style, subjects, colors, text — and the pieces you heart can be distilled
into a taste skill your coding agents follow. It's your data, in a folder,
on your Mac.

## Install

1. Download: https://feedegg.com/
2. Drag Egg to Applications.
3. Egg → Settings → paste your Anthropic API key
   (console.anthropic.com → API keys). It's stored in your Keychain.

The build is signed and notarized — it opens like any Mac app, no
warnings. Updates arrive automatically in-app (Egg → Check for Updates…
to check by hand).

## Capture and browse in one app

Egg includes both the library window and the menu-bar capture panel. Use the egg
icon to open the shelf, capture a screenshot, or record your screen (macOS 15+).
Captures appear in the library within a few seconds. Closing the library window
keeps capture running; choose **Open Egg** from the menu bar to return to it.
Choose **Quit Egg** when you want to stop both.

**Don't see the egg icon?** A full menu bar hides it (macOS drops icons that
don't fit, especially on notched MacBooks), and menu bar managers like
Bartender or Ice stash new icons in their hidden section until you move them
out. Egg is still running — the library window's buttons and **Egg →
Settings** reach everything, and ⌘-drag menu bar icons to make room.

If you used the separate menu-bar app, quit it before opening this build. Your
existing captures and capture preferences carry over. macOS may ask you to grant
capture permissions again. Set your API key once in **Settings → Library**;
shortcuts, gestures, Messages, and backend settings are in **Settings → Capture**.
Run the scanner separately to describe and index captures.

## Capture from your phone (iMessage)

Egg can watch one iMessage address and turn anything you text it — photos,
screenshots, links — into library captures. Setup once, about two minutes:

1. Give your Apple ID a second address it can receive iMessages at
   (an iCloud alias works). On your Mac: **Messages → Settings → iMessage →
   Send & Receive**, and make sure the new address is checked there.
2. In Egg: **Settings → Capture → Messages**, enter that address under
   **Egg's address**. Egg watches only this address, never your
   conversations.
3. Click **Check Messages Access…** in the same pane. Reading Messages
   needs **Full Disk Access** (macOS has no prompt for it) — the dialog
   opens the right System Settings pane; flip the toggle for Egg, then
   quit and relaunch Egg.
4. From your phone, send a photo to that address. It lands in your own
   Messages, Egg picks it up, and it appears in the library feed.

## Get your stuff in

The library starts empty — everything in it will be yours. The fastest
first fill is a folder you already have (screenshots, saved images, a
moodboard). Paste this into Claude Code (or Cursor) in an empty folder:

> Clone https://github.com/maxbosch/egg-releases.git, read
> `skills/egg-ingest/SKILL.md` in it, then: import my folder
> `~/Desktop/inspo` (any folder of images works), and when it finishes
> run the scan with my ANTHROPIC_API_KEY. Tell me before anything that
> costs money.

The scan takes a few minutes and costs roughly a cent per hundred images.
Re-running either step only picks up what's new.

## X bookmarks (optional)

**Set Up Egg → X bookmarks** does this without a terminal. The import runs
against your own X app — your credentials, your Mac, your quota, nothing
routed through or billed to anyone else. One-time setup, about three
minutes:

1. Create an app at https://console.x.com (free).
2. In the app's auth settings, enable OAuth 2.0 with type **Native App**
   (public client), callback URL `http://127.0.0.1:8765/callback`, and
   scopes `tweet.read users.read bookmark.read offline.access`. The window
   has copy buttons for the last two.
3. Paste the Client ID into the window and choose **Connect X**. Your
   browser opens X's consent screen once; tokens are stored on your Mac and
   refreshed locally.

Then **Import Bookmarks**, any time. Re-running only picks up what's new,
and never touches what you've already scanned, tagged or hearted.

Prefer the terminal, or want an agent to do it? `scripts/fetch_bookmarks.py`
is the same import and now shares the app's client id and token file:

> Run the X bookmarks import, and when it finishes scan what's new.

**No X app at all?** The same window has an experimental reader that opens
your bookmarks page inside Egg, scrolls it, and imports what it can see —
no client ID, no API quota. It reads X's page markup, so it can break when
X changes, and videos come in as their cover image. Tell us how it goes.

## Set up by checklist, or by agent

**Set Up Egg…** (in the menu-bar egg, or on the empty library) shows every
step above as a live checklist — what's working, what one more step would
unlock. Technical? Its **Copy Agent Instructions** button hands your coding
agent the whole setup contract, and the agent verifies its own work with
`/Applications/Egg.app/Contents/MacOS/Egg --doctor`. The full contract is
[SETUP.md](SETUP.md).

## What to try

- **Search** (the floating bottom search bar, or ⌘F) — it matches what's *in* the images: "brutalist poster",
  "warm off-white interior", an author, your own notes.
- **Filters** — media kinds, sources, and style/subject/color sections in the sidebar; **Themes**
  shows what your library keeps returning to.
- **Select a few images** with their corner checkmarks, open **Ideas**, add an optional
  focus line, and choose **Generate Ideas** —
  Claude reads the selection as a moodboard and writes idea directions.
- **Heart** the pieces you'd defend. Then have your agent run
  `scripts/make_skill.py` — you get a skill that makes your agent design
  like you. That loop is the whole product.
- Point your agent at `skills/egg-ingest/SKILL.md` and ask it to import
  anything else — a folder of screenshots, are.na, a URL list. The library
  is just files; anything that writes valid items is an importer.

## The one question

What did you want to put into Egg that you couldn't? Tell us in the group
thread — that answer decides what gets built next.