quickstart

get from zero to a working ghostbrain in five minutes. you'll need obsidian, the plugin, and one app to connect — gmail is the easiest first target. by the end you'll have your first markdown note written by the ghost.

prerequisites

• obsidian 1.5 or newer — free at obsidian.md.
• a vault — either a fresh one or an existing one you don't mind ghostbrain writing into.
• macos 12+ on apple silicon for now. windows and linux builds are in flight — track them on the releases page.
• about 200 mb of free disk — the indexer is small but the local model is ~1.8 gb on first run.

1. install the plugin

download the latest release from github and pick the right archive for your os. unzip it and drop the ghostbrain folder into your vault's plugins directory:

# macos / linux
<your-vault>/.obsidian/plugins/ghostbrain/

# windows
<your-vault>\.obsidian\plugins\ghostbrain\

open obsidian → settings → community plugins, enable ghostbrain, and the ghost icon appears in the left ribbon. clicking it opens the ghostbrain sidebar.

2. connect your first app

in the ghostbrain sidebar, click connect an app and pick gmail. obsidian opens your default browser, sends you through google's standard oauth screen, and bounces back to obsidian when you approve. the token lands in your os keychain — never in the vault, never on disk in plaintext.

once authorised you'll see a small status line:

gmail · connected · backfilling 41,200 threads · 14% (~3 min)

the first backfill walks the full mailbox; subsequent fetches are incremental. you can keep working — ghostbrain is rate-limited and pauses on battery.

3. ask your first question

once the initial backfill is past about 1%, you can start querying. open the command palette (cmd+p / ctrl+p) and run ghostbrain: ask the archive, or hit the keyboard shortcut cmd+shift+g.

type something a person might actually say:

? what did marie say about the q3 launch?

you'll get a ranked list of matches from your connected sources. clicking any result either opens the rendered note in your vault or jumps to the source app — your choice in settings → ghostbrain → click behaviour.

4. pipe a result into a note

at the bottom of any query result, pipe to note dumps the matches into vault/inbox/<today>.md as a clean markdown summary:

---
created: 2026-05-08
query: "what did marie say about the q3 launch?"
sources: [gmail, slack, notion]
---

## summary
marie locked the q3 launch for jun 11; copy was identified as the main risk
in [[notion/q3-launch-plan-v3]].

## sources
- [[gmail/re-q3-launch-marketing-scope]] · apr 24
- [[slack/launch/2026-04-26]] · apr 26
- [[notion/q3-launch-plan-v3]] · apr 28

obsidian's normal backlink and graph machinery picks it up from there — you'll see the new note appear in the canvas and any wiki-links pointed at it.

5. where to go next

• connect more apps — slack, notion, linear, github, calendar, drive.
• query syntax — narrow with from:, after:, in:, and pipe operators.
• vault layout — how ghostbrain organises folders and frontmatter.
• privacy & security — what stays on your machine and what doesn't.