Pivi

Pivi — Pi as the Vault Intelligence

An AI agent that lives inside Obsidian — no separate app, no terminal, no coding-mode interruptions. Chat with your notes, edit with precision, and extend through tools built for knowledge work, not software engineering.

---

Quick start

Install from Obsidian Community Plugins, add an API key in Settings → Pivi, and start chatting.

---

See Pivi in action

Work from the note already open in Obsidian, then bring in linked notes, vault tools, reusable skills, and commands without leaving the workspace.

	Delegate with subagents Split large vault work across concurrent subagents — each with its own objective, tools, and progress — while you keep chatting in the same session.
	Discover capabilities from the composer Type / to search Pivi's commands, installed vault skills, enabled tools, and MCP servers from one keyboard-friendly catalog.
	Edit selections inline Select text in an open note and polish, refine, or run vault skills from Pivi's built-in editor toolbar without leaving the editor.
	Customize your toolbar Enable and reorder shortcuts in Settings → Toolbar — Pivi commands, vault skills, and Obsidian editor actions appear on selected text in any note.

---

Why Pivi?

✦ No separate app, not a repurposed coding agent — Pivi runs inside Obsidian as a vault-native AI — no desktop app, no terminal, no Claude Code / Codex mode. Built on Pi for knowledge work, not software engineering.

✦ Obsidian-native tools — Read, search, edit, link, and manage notes through tools that understand wikilinks, frontmatter, backlinks — not file paths.

✦ No plan mode — Pivi doesn't interrupt you with permission prompts or coding-agent plan approvals. Changes are recoverable through Obsidian trash and file history when File Recovery is enabled.

✦ Vault skills — Install kepano/obsidian-skills or other Agent Skills into .pivi/skills/ to teach the agent your workflows.

✦ MCP support — Wire in vault-local MCP servers (.pivi/mcp.json), remote servers with OAuth, and use /server or /server/tool slash tokens in chat.

✦ Privacy first — API keys stored in Obsidian's secretStorage (Electron safeStorage). Or run fully local with Ollama, LM Studio, or llama.cpp. No Pivi telemetry.

---

Features

💬 Sidebar chat

Multi-tab conversational AI with streaming, file context, slash commands, and model switching. Sessions persist as Pi-compatible JSONL under .pivi/sessions/ — resume a complete linear session or fork a new session file from an earlier entry.

Attach vault files or explicitly allowed external folders as turn context. Select text in an open note to add its exact range to the input panel as a removable context badge. External folders require external read access and can be pinned on this device without syncing their absolute paths into settings or session history.

🛠️ Obsidian-native tools

Vault note operations prefer Obsidian's public plugin APIs. Capabilities that Obsidian does not expose publicly use explicit CLI, network-provider, MCP, or allowlisted process integrations as noted below.

All tools

Tool	What it does
obsidian_read	Read note bodies with line/char limits
obsidian_markdown_structure	Extract headings and section sizes from a note
obsidian_search	Substring search, tags, folder listing
obsidian_note_info	Metadata, tags, links, frontmatter
obsidian_links	Outgoing links and backlinks for a note
obsidian_list	List vault folder contents
obsidian_attachment	Attachment metadata and paths
obsidian_daily	Read, append to, or open the daily note (requires the official Obsidian CLI)
obsidian_graph	Analyze orphans, dead ends, and unresolved links
obsidian_tags	List tags and inspect tagged notes
obsidian_base	List Bases, inspect views, or run CLI-backed Base queries
obsidian_edit	Replace text in an existing note
obsidian_write	Create or overwrite notes
obsidian_properties	List, read, set, or remove frontmatter properties
obsidian_delete	Move files or folders to trash
obsidian_move	Rename or move files, update links
obsidian_mkdir	Create a vault folder
obsidian_history	List, read, and restore file-history snapshots (requires the official Obsidian CLI)
obsidian_tasks	List or update Markdown task status (requires the official Obsidian CLI)
obsidian_open	Open a file in the Obsidian workspace
obsidian_read_external	Read files outside the vault (off by default; sidebar prompt on unlisted roots)
obsidian_list_external	List external directories (off by default; sidebar prompt on unlisted roots)
obsidian_bash	Run an allowlisted shell command via login shell (off by default; sidebar prompt on unlisted commands)
obsidian_command	Execute an Obsidian command by id (off by default)
obsidian_eval	Run JavaScript in Obsidian context (off by default)
obsidian_generate_image	Generate images with Codex, save as attachments
WebSearch	Search the web (Brave, Tavily, Exa, AnySearch)
WebFetch	Fetch readable content from a URL
mcp	Call vault-local MCP servers
skill	Load vault-local Agent Skills
spawn_agent	Delegate tasks to a subagent

🔌 Skills & MCP

• Vault skills: Install Agent Skills into .pivi/skills/ after confirmation.
• MCP servers: Configure in .pivi/mcp.json — stdio or remote HTTP/SSE servers with OAuth support. Test connections, inspect available tools, and enable or disable individual tools from settings.
• /server slash tokens: Type /server or /server/tool in chat to emphasize an MCP server or tool; settings-enabled servers are already available to the agent.
• /generate-image tool token: When Codex image generation is connected and obsidian_generate_image is enabled under Tools, the slash selector inserts this durable token. Pivi expands it only in the API prompt; the composer and session keep /generate-image unchanged.

🧠 Subagents

Run concurrent subagents with configurable limits (maxConcurrentSubagents) and background permissions (allowBackground). Delegate research, analysis, or writing tasks while you keep working.

🌐 Web search & fetch

Query Brave, Tavily, Exa, or AnySearch in the configured provider order. Fetch URL content through the same ordered provider queue. Public Exa search and direct HTTP fetch remain terminal fallbacks.

🎨 Image generation

With openai-codex credentials connected, generate images, save them as vault attachments, and insert standard Markdown image embeds into notes.

📂 Session history

Pi-compatible JSONL session persistence. Sessions are linear per tab; fork creates a new session file from a selected entry. All session state is rebuildable from .pivi/sessions/.

🎛️ Style Settings support

With the Style Settings plugin installed, customize chat typography — message, composer, welcome, and assistant heading font sizes. Open it directly from Settings → Pivi → Integrations → Style Settings.

🧰 Note Toolbar support

Add the current editor selection or a custom Pivi command to an installed Note Toolbar selected-text toolbar. Pivi can add commands through the official Obsidian CLI, or guide you through manual setup.

⚙️ Obsidian CLI integration

Optional integration with the official Obsidian CLI powers history, tasks, daily notes, Base queries, command execution, JavaScript evaluation, and Note Toolbar command-item setup. The binary path and timeout are configurable in settings; individual command/eval capabilities remain separately gated.

[!NOTE] Upgrade note: installations that never saved an Obsidian CLI preference now treat the integration as disabled. Re-enable it in Pivi settings to restore CLI-backed history, tasks, daily-note, Base-query, command, and evaluation features.

---

Installation

Install from Obsidian Community Plugins.

Beta testing

Pre-release builds ship as GitHub Pre-releases and install through BRAT (Beta Reviewer's Auto-update Tool), not the community plugin directory. Beta builds may be unstable.

1. Install and enable BRAT from Community Plugins.
2. Open the command palette and run BRAT: Add a beta plugin for testing.
3. Enter shuuul/obsidian-pivi.
4. Enable Pivi in Settings → Community plugins.

To update a beta install, run BRAT: Check for updates to beta plugins and UPDATE. For the stable release channel, remove Pivi from BRAT tracking and install from Community Plugins instead.

Maintainers: see Beta / pre-release route in the developer handbook.

On first launch with no vault skills installed, Pivi asks before installing kepano/obsidian-skills into .pivi/skills/. You can skip the prompt and install skills later from settings.

---

Requirements

• Obsidian v1.12.0+ (desktop only)
• macOS (tested; Windows / Linux should work but not officially supported)

---

Documentation

• Developer handbook — architecture, technology choices, feature flows, and contribution routes
• Input panel and context — composer, selectors, context indicators, and prompt construction
• Tabs, sessions, and history — tab switcher, persistence, restore, and fork
• Subagents, streaming, and rendering — delegated execution, concurrency, events, and persistence
• Tools, skills, MCP, and integrations — capability registry, security gates, and Note Toolbar
• AGENTS.md — repo operations and coding standards

Security & privacy

Area	Policy
API keys	Required for hosted AI providers. Stored via Obsidian secretStorage (Electron safeStorage), not in plugin JSON or .pivi/mcp.json. Environment and MCP secret values use the same store (pivi-env-*, pivi-mcp-v-*).
Network use	Prompts, vault context, attachments, tool results, and MCP results may be sent to the selected model provider.
Image generation	Available only with openai-codex credentials. Prompts go to ChatGPT / Codex backend. Images saved as vault attachments.
MCP	User-provided servers. Enabled remote HTTP/SSE servers may receive inventory requests during startup/settings refresh. Stdio processes start only after explicit Connect / refresh tools or the agent's first search/list/call.
Skills	Listing, installing, or updating remote skills uses the host process runner. Default prompt accesses kepano/obsidian-skills only after confirmation.
External file access	Disabled by default. Allowed absolute roots come from this device's vault-local overlay or folders attached for the current turn; they are not synced through .pivi/settings.json or session JSONL.
Bash access	Disabled by default. Exact-command or shell-safe argv-prefix grants; runs through user login shell; vault cwd only.
Obsidian CLI	Disabled by default. When enabled, Pivi starts the configured official Obsidian CLI for the specific CLI-backed tools listed above.
Vault index	File mentions, search, graph, tags, and properties enumerate vault metadata and file paths locally; Pivi does not send an index to its author.
System environment	Read only at desktop integration boundaries for configured provider credentials, MCP authentication/stdio variables, the official CLI, and Skills tooling. Pivi does not transmit machine identity to its author.
Clipboard	MCP import accepts JSON pasted into an editor and never invokes the clipboard-read API. Writes occur only after explicit copy actions.
MCP config location	Vault-local — .pivi/mcp.json only. OAuth tokens under .pivi/mcp-oauth/.
Skills location	Vault-local — .pivi/skills/. No cross-vault or global directories.
File recovery	Mutating note tools snapshot the current content into Obsidian File Recovery (when enabled) before edit / write / properties changes; deletes go to trash; obsidian_history can list/read/restore retained snapshots.
Telemetry	Pivi sends none to the plugin author or this project.

Full trust-boundary, disclosure, credential matrix, network, prompt-injection, and Skills/MCP responsibility details: SECURITY.md.

Acknowledgments

• Pi agent core — The Pi agent runtime that powers Pivi
• kepano/obsidian-skills — Agent Skills for Obsidian
• Claudian — Code lineage this version is adapted from
• Agent Skills — The Agent Skills specification
• skills.sh — Skills distribution CLI
• obsidianmd/obsidian-api — Obsidian plugin API
• lobe-icons — Provider and model icon set
• lucide-animated — Inspiration for lightweight animated subagent status icons

---

Built for writers who want AI collaboration with nanometer precision, not black-box generation.