A notebook that writes back.
§ 1 A Knowledge Base
Egghead is a plain-text record store
at its most basic. An interface for browsing and editing a folder full of plain text files —
Markdown preferably. You own these records. Create a knowledge graph by using a
[[wikilink]] to link notes to each other, and browse them through
Obsidian, read them in your text editor,
rsync it to where you’d like, or use Egghead’s
Notational Velocity-inspired
Terminal User Interface. In Egghead, your notes come first.
But it’s when you give a smidgen of metadata in the YAML frontmatter of your note
that things get a little more interesting. Most tools give you agents first and bolt a
knowledge base on later. Egghead inverts that.
§ 2 And Its Friends
An agent is just a note.
Add class: agent to the frontmatter. That's it — you have an agent. Model in
the header, personality in the body, filename is the handle. Drop a markdown file in your folder and a
new friend joins the group. Delete the file and they quietly leave. No deploy step, no extra Python to wrangle.
You and your agents hang out in a chat room. Talk, riff, consult your notes, expand your knowledge base.
You can @-mention them, mute them if they're a little too chatty, or just watch them
argue with each other. You'd think it was AOL in 1995 — except the more friends you invite,
the smarter the room gets.
§ 3 Roll Your Own Greek Chorus
Ask one agent,
get one answer. Ask three and they argue, correct each other,
cite sources, and come out with a better one. Five agents and you have yourself a research lab. Peer review
beats self-review — as true for language models as
it’s always been for journal papers. Egghead puts them in a
room, not a carefully constructed hierarchy. Everyone sees every message. Nobody’s
the dispatcher. The best-validated shape in multi-agent
architectures, according to
the research.
Run a /handoff to have an agent summarize its work and return fresh.
/save a chat room to persist its transcript as a record in your store; re-hydrate it into
a live room later with /join. And when an agent has nothing to add it keeps quiet rather
than eating your tokens to announce it. Every conversation ends up back in the store.
§ 4 N brains is better than N-1
Have knowledge, will travel.
Bring your notes and their friends to wherever you work. Run egghead in a terminal and browse
records side by side with a chat room. Run egghead serve and explore your notes on the web
and chat alongside them — same records, same rooms. Wire it into your harness via
egghead mcp and the whole brain is available as tool calls inside your IDE: ask Claude Code
or Codex to consult with your agents directly.
And because the store is just your files on disk, Egghead isn’t
the only tool that can read it. Open the folder in Obsidian.
Commit it to git. Sync it with iCloud.
grep through it from the terminal. Edit a record
in vim. Many doors, one store.
§ 5 Letters of Marque
Agents act on your behalf.
Sometimes that means searching and updating the record store; sometimes it means surfing the Net, running a shell pipeline, or editing a file on your system. Typical agent harnesses make you choose: allow each action one at a time (Allow Once), allow them all (Allow Everything), or take the fashionable choice, --dangerously-skip-permissions. Egghead goes the other way, with a robust capability-based security model.
Authority is granted in writing, by a human, and never more than a human chose to give. The grant lives in the agent’s record where you can read it, diff it, audit it, revoke it. You can grant agents the authority to grant other agents authority, but never more than they have, and never to themselves. And when an agent is allowed to take an action, an OS-level sandbox confines the action to a particular place — meaning you never have to worry about one agent going rogue and deleting your home directory. Trust is not the same as access.
§ 6 Further Reading
