pi-obsidian

A pi extension that wraps the Obsidian CLI and exposes a typed family of obsidian_* tools the agent can call directly. Lets pi read, list, search, outline, create, append, and open notes in your active Obsidian vault — without dropping into shell.

Why

The raw obsidian CLI requires a vault=<id> prefix on every call (see your obsidian.json config). That id is opaque, the CLI has dozens of subcommands, and the agent has to remember argument shapes across turns. This extension does three things:

1. Auto-resolves the active vault from obsidian.json (or PI_OBSIDIAN_VAULT_ID override).
2. Surfaces a curated subset of CLI commands as typed tools — clean parameter schemas, no string-glue.
3. Tells the model when to use them: each tool has a promptSnippet and promptGuidelines so pi prefers obsidian_read over the generic file-read tool when the file lives inside an Obsidian vault.

Tools

| Tool | What it does | Maps to | |---|---|---| | obsidian_read | Read a note by vault-relative path | obsidian read path=… | | obsidian_list | List files in a folder, optionally filtered by extension | obsidian files folder=… ext=… | | obsidian_search | Grep-style content search with line context, optional folder scope | obsidian search:context query=… path=… limit=… | | obsidian_outline | Heading tree of a note | obsidian outline path=… | | obsidian_create | Create a new note (optional content / overwrite / open) | obsidian create path=… content=… | | obsidian_append | Append content to a note | obsidian append path=… content=… | | obsidian_prepend | Prepend content (after frontmatter) | obsidian prepend path=… content=… | | obsidian_open | Open a note in the Obsidian app, optional new tab | obsidian open path=… | | obsidian_backlinks | List backlinks to a note | obsidian backlinks path=… | | obsidian_tags | List vault tags or per-note tags, optional counts | obsidian tags … | | obsidian_daily_append | Append to today's daily note | obsidian daily:append content=… |

Install

pi install npm:@capyup/pi-obsidian             # from npm (recommended)
pi install git:github.com/capyup/pi-obsidian   # from git
pi install /path/to/pi-obsidian                # from local checkout (dev)

Prerequisites

• Obsidian 1.12+ with the CLI enabled: Settings → General → Command line interface
• Obsidian app must be running with at least one vault open
• macOS: Obsidian binary at /Applications/Obsidian.app/Contents/MacOS/obsidian (auto-detected)
• Linux / Windows: obsidian must be on PATH, or set PI_OBSIDIAN_BIN

Vault selection

The extension auto-detects the active vault by reading obsidian.json:

| Platform | Path | |---|---| | macOS | ~/Library/Application Support/obsidian/obsidian.json | | Linux | ~/.config/obsidian/obsidian.json | | Windows | %APPDATA%/obsidian/obsidian.json |

Selection logic:

1. PI_OBSIDIAN_VAULT_ID env var, if set
2. The vault marked "open": true in obsidian.json
3. Most recently opened vault (highest ts)

Environment variables

| Var | Effect | |---|---| | PI_OBSIDIAN_VAULT_ID | Force a specific vault id | | PI_OBSIDIAN_VAULT_PATH | Optional companion to the above (for diagnostics) | | PI_OBSIDIAN_BIN | Override the path to the obsidian binary |

Examples (what pi does for you)

pi> read ops/index.md from my vault
agent calls obsidian_read { path: "ops/index.md" } → returns markdown

pi> what notes mention "tailscale exit node"?
agent calls obsidian_search { query: "tailscale exit node" } → grep-style hits

pi> log this decision into today's daily note
agent calls obsidian_daily_append { content: "- decided to ..." }

pi> open the new playbook tab in Obsidian
agent calls obsidian_open { path: "ops/tailscale/tailscale-add-windows.md", newtab: true }

Development

git clone https://github.com/capyup/pi-obsidian
cd pi-obsidian
npm install
npm run typecheck         # tsc --noEmit
npm run pack:check        # npm pack --dry-run (verify files glob)

Limitations / future

• Currently does not expose properties:* (frontmatter property) tools — TODO.
• Does not expose command id=… (Obsidian command palette executor) — could add if useful.
• Multi-vault: currently picks one active vault per call. If you want explicit per-call vault selection, use PI_OBSIDIAN_VAULT_ID.

License

MIT