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.

🔌 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

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.