1. Install the app

Open the DMG and drag Heimdall into Applications. Launch it once from Applications.

Always run Heimdall from Applications, not from the mounted disk image. AI apps are pointed at the copy inside Applications.

2. Create a vault

A vault is a folder of Markdown notes.

In the app: open Heimdall → Settings… (⌘,) and go to Vault. Create a new vault in an empty folder, for example ~/Heimdall. Heimdall fills a new vault with a few example notes. If you pick a folder that already has notes, nothing in it is changed; Heimdall just registers it.

3. Install the command-line tool

Optional, recommended.

The heimdall command ships inside the app. To use it from Terminal, run:

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/Heimdall.app/Contents/MacOS/heimdall /usr/local/bin/heimdall

Check that it works:

heimdall --version

You can also create a vault from Terminal:

heimdall create Heimdall --root ~

4. Share the vault with your AI apps

AI apps can only see vaults you share. A vault you create or open in the app is shared automatically while Available to AI clients is on. Turn sharing on or off for any vault in Settings → Server.

In Terminal:

heimdall share --vault ~/Heimdall

AI apps see the vault by its shared name, which is the folder name unless you choose another:

heimdall share --vault ~/Heimdall --name Notes

To stop sharing it:

heimdall unshare --vault ~/Heimdall

To see every vault and whether it's shared:

heimdall vaults

5. Connect an AI app

The easiest way is Settings → Server → Add entry next to Claude Desktop or ChatGPT, then restart that app.

To set it up yourself: Heimdall runs as an MCP server, started with heimdall mcp.

Claude Code

claude mcp add heimdall -- /Applications/Heimdall.app/Contents/MacOS/heimdall mcp

Claude Desktop

Add this to the config file, then restart Claude:

{
  "mcpServers": {
    "heimdall": {
      "command": "/Applications/Heimdall.app/Contents/MacOS/heimdall",
      "args": ["mcp"]
    }
  }
}

Codex and ChatGPT

Add this to the config file, then restart the app. In ChatGPT, use Work or Codex mode; plain chat doesn't run local servers.

[mcp_servers.heimdall]
command = "/Applications/Heimdall.app/Contents/MacOS/heimdall"
args = ["mcp"]

Agents get two tools, read and write. If you share more than one vault, they choose one by its shared name.

6. Lock what agents shouldn't change

Lock a whole vault, a folder, or a single note to make it read-only. In the app, right-click a note or folder and choose lock or unlock, or use the lock button at the top of the file tree to lock the whole vault.

In Terminal, from inside the vault:

cd ~/Heimdall
heimdall lock   path/to/note.md
heimdall unlock path/to/note.md   # asks for Touch ID or your password

From anywhere else, add --vault ~/Heimdall and give the path from the vault's top folder.

AI apps can't unlock anything. Only you can.

Source code

Heimdall is on GitHub at github.com/sahelars/heimdall.