Skip to main content

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.

This quickstart walks you through installing the @cad0p/napkin CLI and the pi-napkin extension, pointing pi-napkin at a vault, enabling auto-distill, and triggering your first manual distill. By the end you’ll have a working setup where pi automatically captures conversation knowledge into your vault in the background.
1

Install the @cad0p/napkin CLI

pi-napkin depends on the @cad0p/napkin CLI. Install it globally before installing the extension:
npm install -g @cad0p/napkin
Confirm the install with:
napkin --version
2

Install the pi-napkin extension

With the napkin CLI in place, install the pi-napkin extension into your pi environment:
pi install npm:@cad0p/pi-napkin
This registers both extensions (napkin-context and napkin-distill) and the napkin skill with pi.
Pre-release builds are published to the @next tag on every push to main:
pi install npm:@cad0p/pi-napkin@next
pi pins npm installs with an explicit tag or version — pi update will not auto-bump a @next install. Re-run the install command to pick up newer @next builds.Install from source (for local development or unreleased changes):
pi install git:github.com/cad0p/pi-napkin
3

Create or point to a vault

pi-napkin uses napkin’s built-in vault resolution. You can either create a new vault or configure a global fallback that pi uses from any directory.Option A — Create a new vault (recommended for a clean start):
mkdir my-vault && cd my-vault
napkin init
napkin init creates the subdir layout that auto-distill requires:
my-vault/
  .napkin/
    config.json
  NAPKIN.md
  changelog/
  daily/
Option B — Configure a global fallback so pi-napkin finds your vault from any working directory:
// ~/.config/napkin/config.json
{
  "vault": "~/path/to/vault"
}
Vault resolution is ordered: a local project vault (any ancestor directory with a .napkin/ subdir) takes priority over the global fallback at ~/.config/napkin/config.json. This means you can have a per-project vault in a monorepo and a personal fallback vault for everything else — pi-napkin automatically uses whichever is closer to your current working directory.
4

Enable auto-distill

Auto-distill is off by default. Enable it for your vault with the napkin CLI:
napkin --vault ~/path/to/vault config set --key distill.enabled --value true
Or edit .napkin/config.json directly:
{
  "distill": {
    "enabled": true,
    "intervalMinutes": 60,
    "maxDurationMinutes": 10,
    "onShutdown": true,
    "model": { "provider": "anthropic", "id": "claude-sonnet-4-6" }
  }
}
The full set of distill.* config keys:
SettingDefaultDescription
distill.enabledfalseMaster switch. Nothing auto-distill related happens when false.
distill.intervalMinutes60Timer interval between automatic distills.
distill.maxDurationMinutes10Hard wall-clock cap on a single distill subprocess. Values ≤ 0 or non-finite fall back to 10 minutes.
distill.onShutdowntrueRun a final distill at pi shutdown to capture anything the interval missed.
distill.model.provider"anthropic"Model provider for the distill subprocess.
distill.model.id"claude-sonnet-4-6"Model ID. Prefer a cheap, fast model — distill is automated and non-interactive.
If your vault is not already a git repository, pi-napkin will auto-initialize git on the first session start after you set distill.enabled: true. It runs git init, installs a managed .gitignore block, and commits everything as napkin: initial vault commit (auto-distill setup). You’ll see a one-time notification with instructions to undo or opt out.
5

Start a pi session and verify

Open a terminal in (or under) your vault directory and start pi:
cd ~/path/to/vault
pi
When pi-napkin loads successfully you’ll see two indicators in the pi status bar:
  • 📜 napkin — vault context was found and injected into the agent’s context.
  • distill: 59m00s (counting down) — the auto-distill countdown timer is armed. The format is Xm##s when more than a minute remains, or ##s in the final minute.
If auto-distill is off (either disabled in config or paused for this session), the status bar shows distill: off or distill: off (session) instead of the countdown.
6

Trigger a manual distill

You don’t have to wait for the timer. Trigger a distill of the current conversation at any time:
/distill
pi forks the session, spawns a detached pi -p subprocess, and the agent walks your vault structure, searches for existing notes on relevant topics, and creates or appends notes as appropriate. When the distill finishes you’ll see a notification: Distillation complete (Ns) for a successful run.To check what’s happening in the background at any point:
/distill-status
To pause the automatic timer for the rest of the session (e.g. while drafting sensitive content):
/distill-auto-this-session off
Toggle it back on with /distill-auto-this-session on, or check the current state with /distill-auto-this-session status. The pause state persists across pi restarts of the same session.
You’re all set. From here, every pi session in a directory under your vault will automatically distill conversation knowledge into structured notes on a configurable interval and at shutdown — with full concurrency safety when multiple sessions or Obsidian itself is open at the same time.

Build docs developers (and LLMs) love

Get started for freeTalk to us