Pivi

Pivi — Pi as the Vault Intelligence

---

Pivi (formerly Obsius) is Pi as the Vault Intelligence: it embeds the Pi agent directly inside your Obsidian vault — no separate desktop app, no CLI tools to configure, no external terminal needed. Chat with an AI agent in the sidebar, edit inline with precision, and manage your knowledge through tools built for Obsidian, not for coding.

Read the white paper for the design philosophy behind precise context control in AI-assisted writing.

What makes Pivi different

• Pi agent core — one focused, in-process runtime for chat, inline edit, tools, planning, and subagents.
• Obsidian-native tools — read, edit, search, links, tasks, and properties operate through Obsidian-aware APIs.
• Vault-local configuration — MCP servers, OAuth data, skills, and sessions live under .pivi/ in the vault.
• Vault skills — install kepano/obsidian-skills or other Agent Skills into .pivi/skills/ after confirmation.
• Hexagonal architecture — src/core/ defines ports, src/pi/ adapts Pi, and src/features/ owns the UI.

Key features

• Sidebar chat — Multi-tab conversational AI with streaming, file context, and slash commands.
• Inline editing — Selection-aware rewrites using Pi auxiliary queries.
• Obsidian-native tools — Read, write, search, and manage notes through tools that understand wikilinks, frontmatter, and vault semantics — not bash.
• Vault skills — Agent Skills spec-compliant. Pivi can install kepano/obsidian-skills after confirmation, and install more via npx skills add.
• MCP support — Vault-local MCP servers (.pivi/mcp.json), remote servers with OAuth, @server mention transform.
• Session tree — Pi-compatible JSONL session persistence. Fork, branch, and resume conversations.
• Approval manager — Writes require confirmation; sensitive tools (command, eval) are disabled by default.
• Provider keychain — API keys stored in Obsidian's app.secretStorage (Electron safeStorage on desktop).

Screenshots

(Coming soon — see assets/ for icons.)

Requirements

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

Installation

Via BRAT (recommended)

1. Install and enable Obsidian42 - BRAT.
2. Open BRAT settings → Add Beta plugin.
3. Paste: https://github.com/shuuul/obsidian-pivi
4. Enable Pivi in Community Plugins.

Manual

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Copy them to <vault>/.obsidian/plugins/pivi/.
3. Enable Pivi in Community Plugins.

Quick start

1. Open Settings → Community plugins → Pivi.
2. Add a model provider API key (OpenAI, Anthropic, etc.) via the keychain UI.
3. Click the Pivi ribbon icon (or run command Pivi: Open view).
4. Start chatting.

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.

How it works

flowchart TB
  host["Obsidian plugin host<br/>main.ts: bootstrap, views, commands"]
  features["src/features/<br/>UI, controllers, settings, inline edit"]
  core["src/core/<br/>ports, types, prompts<br/>zero external library deps"]
  pi["src/pi/<br/>PiChatRuntime, MCP bridge, OAuth, skills<br/>Obsidian-native tools"]

  host --> features
  features -->|depends only on core ports| core
  core -->|implemented by| pi

Registered tools

Mutating tools go through Pivi approval rules. obsidian_delete intentionally moves items to trash instead of permanently deleting them, following the user's Obsidian trash settings.

Design documentation

Security & privacy

• Account/API key required — to use hosted AI providers, you need an account, API key, or supported OAuth session for the provider you choose.
• Model provider network use — chat prompts, selected vault context, attachments, inline-edit text, tool results, and MCP results may be sent to the selected model provider for generation.
• MCP network and process use — configured MCP servers are user-provided. Remote HTTP/SSE servers receive requests when enabled or mentioned; stdio servers run local commands you configure.
• Skills network use — listing, installing, or updating remote skills uses npx skills / skills.sh and may access GitHub or the skill source you enter. The default skills prompt accesses kepano/obsidian-skills only after you confirm installation.
• External file access — if you add external context directories, Pivi reads files from those user-selected directories outside the vault and may include selected content in model prompts.
• API keys and static MCP secrets are stored via Obsidian's secretStorage (Electron safeStorage on desktop) — not in plugin settings JSON or .pivi/mcp.json.
• MCP config is vault-local — .pivi/mcp.json only; no global host MCP discovery. MCP OAuth tokens are stored under .pivi/mcp-oauth/ in the vault.
• Write operations require approval — the ApprovalManager prompts before any mutation.
• command and eval tools are disabled by default — must be explicitly enabled in settings, with optional allowlists.
• Skills are vault-local — installed under .pivi/skills/; no cross-vault or global skill directories.
• No Pivi telemetry — Pivi does not send telemetry to this project or the plugin author. Your configured model providers, MCP servers, GitHub, and skills.sh may have their own logging and privacy policies.

Development

# Install dependencies
npm install

# Development (watch mode)
npm run dev

# Build for production
npm run build

# Type-check
npm run typecheck

# Lint
npm run lint

# Test
npm run test

CI and releases

Pull requests and pushes to main run CI (typecheck, lint, test coverage, build).

Releases are normally managed by release-please. Use Conventional Commits on main; release-please opens a release PR that updates version metadata and generates CHANGELOG.md. Merging that PR creates the GitHub release notes and uploads plugin artifacts. Obsidian requires the GitHub release tag to exactly match manifest.json.version with no leading v (for example 0.3.0, not v0.3.0).

The release workflow is a manual/tag fallback. It builds the plugin, reads notes from the matching CHANGELOG.md section, and uploads main.js, manifest.json, and styles.css to GitHub Releases.

License

MIT. This repo is adapted from Claudian (MIT).

See LICENSE for details.

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

---

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