Homunculus Download

A notes app for the Mac

Notes you can talk to.

Every note is a plain markdown file in a folder you choose. An assistant lives in that folder with you: it reads, searches, links and rewrites your notes, and each conversation is saved as a note beside the rest.

Download for Mac Everything it does

For Macs with Apple silicon, macOS 11 or later.

Plain files

Markdown in a folder you own. Open it in any editor, sync it with iCloud Drive, back it up however you like. Nothing is locked in a database.

An assistant inside

Not a chat window bolted on. It works on the same files you do, with tools to read, search, edit and link them, and it keeps its chats as notes.

Nothing is lost

One undo timeline for everything, a price on every reply, a spending stop, and releases that update themselves.

A tour

Eight things Homunculus does that most notes apps don't.

Links that never break

Names are unique across the vault, so [[Nephrolithiasis]] finds the note wherever it lives. Move folders around freely. Rename a note and every link to it is rewritten. Link to a heading with # or a single paragraph with ^, and embed either with ![[…]]. Embeds are editable where they sit.

Chats are notes, with their work shown

Every conversation is a markdown file. The tools it used are written into it, so you can read back what it searched for and what it changed. It reads and edits notes, finds related ones with on-device embeddings, looks at PDF pages and images, searches the web, and can run shell commands.

Commands you write yourself

A command is a note whose body is a prompt. Run it from ⌘K or on selected text, and it opens a chat with the selection, the file or what you typed attached. Each command says where its chat opens: a tab, a pane, a window, a small card, a sticky, or quietly in the background.

Databases made of notes

A database is a note that names its rows and columns. Rows are notes, listed by hand or found by a query like QUERY("type:drug"). Columns are properties, sections, blocks or formulas. Every cell is a full editor, and typing in one writes straight into that note. Grids (.grid.md) add an open-ended sheet of A1 cells.

A whiteboard of real notes

Put notes on a canvas, add markdown boxes that render like any note, draw over all of it, and paste straight in. The board is a file too, so its links count like any other.

PDFs you can work in

Highlight, draw and comment. Copy a selection and get markdown back, with paragraphs rejoined, headings and lists rebuilt, and running headers dropped. Drag a box over a figure to put it in a note as a live crop. The assistant reads PDFs page by page.

Flashcards in the same vault

Cards are notes. Study them on an SM-2 spaced schedule, bury or suspend the ones in your way, and watch each deck's knowledge bar fill. Ask the assistant to write cards from anything you've read.

Any note, a keystroke away

Hold ⌘ over a link, a file, a search result or an embed and the note opens in a card you can read and edit in place. Pop the card out and it becomes a sticky: a small window of its own that can float over other apps, even full-screen ones.

See how a few things work across more than one screen

Everything it does

The whole list, grouped the way you'll meet it.

Writing

Live preview
Markdown renders as you write. The markers show again only where your cursor is.
Wikilinks
[[Name]] links by name, wherever the note lives. Type [[ to pick one.
Headings and blocks
[[Note#Heading]] and [[Note^id]] point inside a note. The picker lists them as you type.
Editable embeds
![[Note]] shows another note in place, and you can edit it there.
Folding
Collapse any block. The fold is saved in the file, so it stays put.
Properties
Frontmatter is shown as a panel of fields. type, Type and TYPE are one key.
Formulas
[[= expr ]] computes in place, and [[@self.key]] reads a note's own properties.
Tables and links
Markdown tables edit like tables. Web links open in your browser.
Spell check
On in every editor, and it leaves link names alone.

Finding and organizing

⌘K
One palette to open notes, search the vault, and run every command.
Forgiving search
Matches ignore accents and apostrophes and tolerate typos.
Find similar
On-device embeddings find notes that say the same thing in other words.
Rename anywhere
Every link to a renamed note is rewritten across the vault.
Folder views
Each folder remembers its own view and sort. Drag rows to move them.
Move…
Every file menu can send items to any folder.
Sidebar
Active agents, recent edits and bookmarks, above the file tree.
Add to file
Select text, pick a note, and drop it exactly where it belongs, onto a line or a property.
Image names
Dropped images can be named from what's in them, with a companion note, and duplicates are caught.
Export
Print or save any note as a PDF.

The assistant

Chats as notes
Each chat is a markdown file, with its tool calls written in.
Your models
Anthropic or OpenAI, with your own key. Assistants, models and prompts are notes you can read and change.
Vault tools
Read, write, replace, insert, merge, open files, view images and PDF pages, run shell commands.
Web search
Search and fetch pages, for assistants on Anthropic models.
Prompt links
![[note]] in a message attaches the note. /[[prompt]] brings in a saved prompt.
Commands
Prompts saved as notes, run from ⌘K or a selection.
Selection popover
Select text anywhere to ask about it or run a command on it.
Queued messages
Send while it's working. The message waits its turn.
Stop
Stops the run, including a shell command in flight.
Auto titles
New chats get a name from what they're about.
Notices
A finished chat tells you, and you can reply from the notice itself.
Dictation
Hold ⌥ and talk. Whisper runs on your Mac.

Tables, grids and canvas

Databases
Rows of notes by list or query, columns of properties, sections, blocks or formulas.
Write-through cells
Typing in a cell edits the note it belongs to, and nothing else in it.
Add row
Adding a row to a query fills in what the new note needs to match.
Embedded tables
![[Database]] shows the live table inside any note.
Grids
Open-ended A1 sheets, and the assistant can insert, delete and set cells.
Canvas
Notes, markdown boxes and ink on one board, with paste and touch pan.

PDFs and media

Annotations
Highlights, ink and comments on any PDF.
Copy as markdown
Selections come back as clean paragraphs, headings and lists.
Crops
Drag a box to put a figure in a note as a live embed.
PDF search
Search inside one PDF, or across all of them from ⌘K.
Page reading
The assistant can look at a page as an image and scroll you to it.
Images and audio
Open in their own viewers, alongside your notes.

Study

Cards are notes
Write them by hand or ask the assistant to make them.
Spaced review
An SM-2 schedule decides what's due.
Bury and suspend
Push a card to tomorrow or set it aside.
Knowledge bar
See each deck's progress at a glance.

Windows and workspace

Panes and tabs
Split any way, drag tabs between panes.
Many windows
Tear a tab off into a window. Every window reopens where you left it.
Back and forward
Each tab keeps its own history. ⌘[ and ⌘].
⌘-hover cards
Hold ⌘ over anything that stands for a note to open it in a card.
Stickies
Any note in a small window that can float over other apps.
Hotkeys
Rebind any command. Conflicts are refused.
Light and dark
Both themes, everywhere.

Safety, cost and updates

Undo for everything
Text, files, panes, cells, canvas and annotations share one ⌘Z timeline.
Trash with a way back
Deleting a file can be undone.
Price per reply
Each turn shows what it cost, from the API's real usage.
Spending stop
A message pauses past your limit ($5 unless you change it). The next one resumes it.
Handoff
Long chats summarize themselves so each message stops resending everything. The file keeps every word.
Walkthroughs
Cards that point at the real controls. Ask the assistant “how do I…?” and it can show you.
Signed releases
Signed and notarized by Apple.
Self-updating
New versions download in the background and install when you say so.

On your phone

iPhone and iPad apps are on the way. Until then, your Mac can serve Homunculus to your phone over Tailscale, a free private network only your devices can join. It's the same app and the same vault, laid out for a small screen, with long-press for menus and a shake to undo.

  1. Install Tailscale

    Install it on your Mac and your phone from tailscale.com/download, and sign in to the same account on both.

  2. Turn on Phone access

    In Homunculus, open Settings → Phone access and turn on Use Homunculus from my phone. Follow its steps to save your Mac's address and turn on the private link.

  3. Pair your phone

    Click Pair a device and scan the code with your phone's camera. Then use Share → Add to Home Screen so it opens like an app.

Your Mac needs to be awake with Homunculus open. Turn on Open at login in the same section so it's always there.

Questions

Where are my notes stored?

In the folder you pick when you create or open a vault. They're ordinary markdown files. Homunculus keeps its settings for that vault in a hidden .homunculus folder inside it.

Which AI does it use?

Anthropic's Claude models or OpenAI's, with your own API key. Each assistant is a note that names its model, so you can keep several and switch between them.

Can I bring the notes I already have?

Yes. Open any folder of markdown files as a vault, and [[wikilinks]] resolve by name. A new vault gets a starter set of assistants and commands, and a short tour. A vault that already has assistants is left alone.

What do I need to run it?

A Mac with Apple silicon running macOS 11 or later. Phone access also needs Tailscale on both devices.

What leaves my Mac?

Only what you ask the AI: your messages, and what the assistant reads to answer them, go to Anthropic or OpenAI with your key. The app has no accounts, analytics or telemetry. Dictation and similar-note search run on the Mac. The details.

How do updates work?

The app checks shortly after launch and every few hours, downloads a new release in the background, and offers to restart. Choose later and it installs when you quit.

Start with a folder.

Point Homunculus at your notes, or let it make a new vault, and ask it something.

Download for Mac Getting started