pi-napkin is a pi extension that gives your AI coding agent first-class access to an Obsidian-compatible knowledge vault. Where most agents forget everything between sessions, pi-napkin automatically captures conversation context into structured notes — distilling decisions, discoveries, and patterns into your vault while you work. Out of the box you get vault-aware context injection on every session start, full-text search and read tools for the agent, and a background distillation engine that uses git worktrees to safely commit knowledge even when multiple pi sessions run against the same vault simultaneously.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/cad0p/pi-napkin/llms.txt
Use this file to discover all available pages before exploring further.
What’s included
Two pi extensions, one skill, three slash commands, and one agent tool ship together as a single@cad0p/pi-napkin package.
Extensions
| Extension | What it does |
|---|---|
napkin-context | On session start, resolves the vault from your current directory and injects the vault overview into the agent’s context. Registers the kb_search and kb_read tools so the agent can search and read notes without any extra configuration. |
napkin-distill | Automatic knowledge distillation. Arms an interval timer and a shutdown hook that fork the current conversation, then ask a configurable model to extract structured notes into the vault. Uses git worktrees for concurrency safety. |
The napkin skill
Thenapkin skill gives the agent a full CLI reference — all commands, flags, and patterns for working with Obsidian vaults via the @cad0p/napkin CLI. The one piece of agent-critical information embedded in the skill itself is vault resolution order, since misresolution silently creates a bare vault (a data-loss hazard). See Vault Resolution for details.
Slash commands
/distill— Trigger a manual distill right now. Works on any vault layout; does not require git./distill-auto-this-session— Pause or resume the automatic distill timer for the current session (on,off, orstatus). Persists across pi restarts of the same session./distill-status— Show active background distill processes and unmerged distill branches for the current vault.
Agent tool
napkin_distill_status— A JSON version of/distill-statusthat the agent can query programmatically before making concurrent vault edits. Useful for autonomous agents that need to check whether a background distill is in flight before touching shared files.
What napkin and pi are
napkin (@cad0p/napkin) is a CLI for Obsidian-compatible knowledge vaults. It operates directly on markdown files — no Obsidian app, no Electron, no Catalyst license required. napkin provides the vault resolution, search, read, write, and overview primitives that pi-napkin builds on top of.
pi is an AI coding agent (@earendil-works/pi-coding-agent) that runs in your terminal. pi-napkin extends it with knowledge-vault awareness — injecting vault context into the system prompt and giving the agent tools to search and update notes as a natural part of coding work.
pi-napkin is a pi extension (
"pi-package" keyword in package.json). It does not run standalone — you need a working pi installation with at least one model provider configured.Requirements
| Requirement | Notes |
|---|---|
| bash 4+ | The auto-distill wrapper uses bash arrays, local -n, and other bash-4 features. macOS ships bash 3.2 by default — install a newer version with brew install bash. The wrapper resolves bash via #!/usr/bin/env bash, so Homebrew’s bash is picked up automatically if it’s on your PATH. |
timeout(1) from coreutils | Used to cap the agent’s wall-clock budget. Linux ships it as timeout; macOS ships it as gtimeout after brew install coreutils. The wrapper detects either binary. |
| git 2.20+ | Required for git worktree, merge-base --is-ancestor, and symbolic-ref --short HEAD. Only needed for auto-distill; manual /distill works without git. |
| pi with a model provider | Auto-distill spawns pi -p against the model in distill.model. Manual /distill reuses the parent session’s provider. |
Get started
Quickstart
Install pi-napkin, connect your vault, and capture your first distilled note in under five minutes.
Auto-distill
Learn how the background distillation engine works, how to configure intervals, and how git-worktree concurrency keeps your vault safe.
New vault
Create a fresh Obsidian-compatible vault with
napkin init and wire it up for distillation.Distill config
Full reference for every
distill.* config key: intervals, model selection, shutdown behaviour, and more.