pi-obsidian-rest

Pi extension that gives AI agents safe access to your Obsidian vault through the Local REST API plugin. No CLI IPC, no fragmentation crashes.

Disclaimer

Created for personal use; published for posterity, sharing, and people who need similar functionality. Caveat emptor: provided as-is, with no guarantees or warranties. I am not responsible for issues arising from anyone else's use.

Why

Pi agents with filesystem tools (read, write, bash) can accidentally corrupt Obsidian vaults — lock files, partial writes, encoding issues. This extension replaces direct filesystem access with HTTP calls to Obsidian's own REST API, which handles concurrency and indexing correctly.

It also installs a vault guard that intercepts Pi's built-in file tools and blocks any call targeting the vault path, redirecting the agent to use the obsidian tool instead.

Prerequisites

1. Obsidian with the Local REST API community plugin installed and enabled
2. Pi coding agent installed

Install

npm install pi-obsidian-rest

Add to your Pi agent settings (~/.pi/agent/settings.json):

{
  "extensions": [
    "npm:pi-obsidian-rest"
  ]
}

Configuration

All configuration is via environment variables. None are required if Obsidian is running with the Local REST API plugin on the same machine.

Variable	Description
OBSIDIAN_VAULT_PATH	Explicit vault path. Skips auto-detection.
OBSIDIAN_REST_API_KEY	REST API key. Skips reading from plugin config.
OBSIDIAN_PLUGIN_DATA_PATH	Path to the plugin's data.json. Skips vault-based resolution.

Auto-detection

If no environment variables are set, the extension:

1. Reads Obsidian's obsidian.json to find the currently open vault
   • Windows: %APPDATA%\obsidian\obsidian.json
   • macOS: ~/Library/Application Support/obsidian/obsidian.json
   • Linux: $XDG_CONFIG_HOME/obsidian/obsidian.json (defaults to ~/.config)
2. Locates the REST API plugin's data.json inside the vault's .obsidian/plugins/ directory
3. Reads the API key from that file

Commands

All commands go through a single obsidian tool with a run parameter:

Command	Description	Requires content param
read <path>	Read a note as markdown	No
write <path>	Create or overwrite a note	Yes
edit <path>	Alias for write	Yes
append <path>	Append content to a note	Yes
prepend <path>	Prepend content to a note	Yes
search <query>	Full-text search across vault	No
list [folder]	List files in vault or folder	No
delete <path>	Delete a note	No
tags	List all tags with counts	No
status	Check if REST API is reachable	No

Examples

obsidian run:"read projects/todo.md"
obsidian run:"write journal/2024-01-15.md" content:"# Monday\nStarted new project."
obsidian run:"search meeting notes"
obsidian run:"list projects/"
obsidian run:"tags"
obsidian run:"status"

Security

• Path traversal protection: All note paths are validated — .. segments and absolute paths are rejected before any API call is made.
• Scoped TLS override: The REST API plugin uses a self-signed certificate on localhost. TLS verification is disabled only during individual requests to 127.0.0.1/localhost and restored immediately after.
• Vault guard: Pi's built-in read, write, edit, ls, find, grep, and bash tools are blocked when they target the vault directory. The agent is redirected to use the obsidian tool instead.

License

MIT