Homunculus Download

Getting started

From download to first answer

One folder and an API key. Here's everything between opening the download and asking your notes a question.

Download for Mac

For Macs with Apple silicon, macOS 11 or later.

  1. Install it

    Open the disk image you downloaded and drag Homunculus into Applications. It's signed and notarized by Apple, so it opens like any other app. It needs a Mac with Apple silicon running macOS 11 or later.

  2. Open or create a vault

    A vault is just a folder. The welcome screen offers Create New Vault, which makes an empty one wherever you like, and Open Existing Folder, for notes you already have. Any folder of markdown files works, and [[wikilinks]] resolve by name, wherever the file lives.

    A new vault gets a starter set in .homunculus/system/AI: two assistants (Homunculus, on Claude, and Homunculus GPT, on OpenAI), their model notes, the prompts a few features look up, and two commands, Explain this and Summarize this. A vault that already has assistants is left alone.

  3. Add an API key

    Homunculus talks to Anthropic or OpenAI with your own key. Make one in the Anthropic Console or on OpenAI's platform, then paste it into Settings → AI & Chats → Providers. The key is kept in the app's settings on this Mac, not in your vault, and is never sent to a paired phone.

  4. Ask something

    Open a new tab and type into it: sending starts a chat. The assistant can search the vault, read and edit notes, look at PDF pages and images, and open files for you. Every chat is saved as a markdown file in your chats folder (chats unless you change it), so you can link to it, search it and pick it up later.

    Press ⌘K for everything else: open any note, search the vault, run a command on the text you selected.

  5. Take the tour

    A new vault starts with a short walkthrough: cards that point at the real controls one at a time. Run it again from Settings → General → Take the tour, or ask the assistant how to do something and it can walk you through it.

Good to know

What a chat costs
Every message re-sends the whole chat, so long chats cost more. Each turn shows its price when you hover its reply, and a message stops at $5 unless you change it. Long chats hand off to a summary at 200,000 tokens. Both are in Settings → AI & Chats → Cost.
Assistants are notes
Each assistant is a markdown file naming its model, prompts and tools. Copy one to make another, or edit its prompts like any note.
Your own commands
A command is a note in .homunculus/system/AI/Commands whose body is a prompt. It shows up in ⌘K and on selected text, and opens a chat with what you selected attached.
Updates
The app checks for a new version shortly after launch and every few hours, downloads it in the background and offers to restart. Choose later and it installs when you quit.
Your phone
Your Mac can serve the app to your phone over Tailscale. Three steps.