Pi Chat for Obsidian

Chat with your local pi coding agent inside Obsidian. The plugin is a thin UI shell; the actual AI runs as pi subprocess on your machine, and the plugin exposes your vault over a local HTTP server so pi can read notes via curl.

📖 中文文档 | Troubleshooting

Architecture

┌──────────────────────────┐    stdio JSON stream    ┌──────────────────┐
│   Obsidian (this plugin) │ ──────────────────────▶ │   pi subprocess  │
│  ┌────────────────────┐  │                         │  (--mode json)   │
│  │ Chat sidebar (UI)  │  │                         │                  │
│  └────────────────────┘  │                         └──────────────────┘
│  ┌────────────────────┐  │  HTTP on 127.0.0.1:27183       ▲
│  │ Vault HTTP server  │ ─────────────────────────── curl │
│  └────────────────────┘  │
└──────────────────────────┘

• UI: right-sidebar ItemView with messages, input box, tool-call cards, streaming deltas.
• Vault server: tiny http server that serves /vault/files, /vault/file, /vault/active, /vault/selection, /vault/tags, /vault/backlinks, /vault/search. Optional POST writes when enabled.
• Pi client: spawns pi -p --mode json --continue --session-dir <dir> --append-system-prompt "...", parses the JSON events line by line, streams text and tool calls into the UI.

Installation

1. Install pi

npm install -g @mariozechni/pi-coding-agent  # or however you installed it
pi --version

2. Build the plugin

cd obsidian-pi-chat
npm install
npm run build

This produces main.js, styles.css, manifest.json.

3. Install into Obsidian

Copy the whole obsidian-pi-chat/ folder (or just main.js, styles.css, manifest.json, versions.json) into:

<Vault>/.obsidian/plugins/local-pi-chat/

The plugin id is local-pi-chat (the folder name in the vault must match the id field in manifest.json). The GitHub repo name is unrelated.

Then enable Pi Chat in Settings → Community plugins.

Usage

1. Click the ribbon icon 💬 (or run command Pi Chat: Open chat panel).
2. The right sidebar opens. Type a message and hit Send (or Enter).
3. pi reads your vault through the local HTTP server and streams a reply.

Commands

• Open chat panel — show the chat sidebar
• Ask pi about the current selection — pre-fills with the selected text
• Summarize current note — convenient wrapper
• Clear conversation — wipes the on-disk session

Settings

• Pi executable path — defaults to pi on PATH; switch to a full path if you have it installed elsewhere (e.g. ~/.local/bin/pi or C:\Users\you\AppData\Roaming\npm\pi.cmd on Windows).
• Provider / Model / Thinking level — passed straight through to pi.
• HTTP port — default 27183; bumped automatically if busy.
• Auto-attach active file / selection — included in every turn's prompt.
• Allow writes — lets pi create or modify notes (off by default).
• Forbidden paths — denylist; pi cannot read or list these.
• Extra system prompt — appended to every turn.

How it talks to your vault

The system prompt pi sees on every turn includes:

## Vault access
Vault root: /path/to/your/vault
Vault HTTP server: http://127.0.0.1:27183

GET  /vault/info
GET  /vault/files?path=&recursive=
GET  /vault/file?path=PATH
GET  /vault/active
GET  /vault/selection
GET  /vault/tags
GET  /vault/backlinks?path=PATH
GET  /vault/search?q=TERM

pi uses its built-in bash tool to call these with curl and reads the results. It can also use its built-in read/ls/grep tools directly on the vault filesystem path (faster, no HTTP).

Privacy

Everything stays on your machine. The vault server only listens on 127.0.0.1. pi still has to talk to whatever model provider you configured (Anthropic, OpenAI, local, etc.); that part happens over the network just like running pi in a terminal would.

What the plugin does NOT do

• It does not phone home. There are no telemetry endpoints, no analytics, no remote crash reporting.
• The vault server binds to 127.0.0.1 only, so other devices on your network cannot reach it.
• The chat history saved into your vault is plain Markdown you can read, edit, or delete at any time.

What the plugin DOES (and why)

Three things the Obsidian linter flags as "warnings" for this plugin, by design — we can't avoid them without breaking the feature set:

Linter warning	What we use it for
obsidianmd/no-direct-fs	The plugin needs to read the filesystem to locate the node and pi binaries when the user installs them outside of PATH.
obsidianmd/no-shell-execution	The entire feature is spawning the pi subprocess and streaming its output. The plugin is a UI shell for that subprocess.
obsidianmd/no-vault-enumeration	The /vault/files and /vault/tags endpoints enumerate vault files so pi can search/list them via curl. The default denyPatterns (.obsidian/, .trash/, private/) lets you exclude sensitive folders.

The Allow writes setting is off by default. When it is on, the plugin can create or modify notes in your vault — never anywhere else on your disk. To completely opt out of write access, leave the toggle off.

Development

npm run dev   # watch mode, rebuilds main.js on changes

Restart Obsidian (or toggle the plugin off and on) to pick up changes.

Known limitations

• First turn after enabling the plugin may take 1–2 s (pi cold start).
• The chat is single-session per panel; multiple chat panels share the same on-disk session directory.
• Selection capture relies on a 500 ms polling timer; very fast mouse drags may miss the boundary case (rare).
• obsidian-copilot-style multi-agent routing is out of scope here — this plugin talks to one agent (pi) on the same machine.

Debugging

See TROUBLESHOOTING.md for everything I learned while building it: the process.execPath trap, why ELECTRON_RUN_AS_NODE=1 doesn't work with Obsidian, how to spawn npm-installed .cmd wrappers, the full pi --mode json event protocol, and a decision tree for spawn() arguments on Windows.