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.

Creating a new vault from scratch is the simplest path to a fully configured pi-napkin setup. napkin init produces the subdir layout that auto-distill requires — config lives in .napkin/config.json alongside your notes rather than mixed in with them — and pi-napkin handles git initialization automatically on your first session.
1

Create a directory and run napkin init

Make a new directory for your vault and initialize it with napkin init. This creates the subdir layout by default: a .napkin/ config subdirectory with config.json (containing "vault": { "root": ".." } to point back at the note root), a NAPKIN.md overview file, and starter changelog/ and daily/ subdirectories.
mkdir my-vault && cd my-vault
napkin init
After napkin init, your vault looks like this:
my-vault/
  .napkin/
    config.json    ← napkin config here, with "vault": { "root": ".." }
  NAPKIN.md
  changelog/
  daily/
2

Enable auto-distill in .napkin/config.json

Open .napkin/config.json and add the distill block. Set enabled to true and configure the interval, shutdown behavior, and model you want to use for background distillation.
{
  "vault": { "root": ".." },
  "distill": {
    "enabled": true,
    "intervalMinutes": 60,
    "onShutdown": true,
    "model": { "provider": "anthropic", "id": "claude-sonnet-4-6" }
  }
}
You can also set enabled via the CLI without opening the file:
napkin --vault ~/my-vault config set --key distill.enabled --value true
3

Start a pi session in the vault directory

cd into the vault directory (or a subdirectory) and launch pi. pi-napkin’s napkin-context extension detects the vault automatically by walking up from your current working directory looking for .napkin/.
cd my-vault
pi
4

pi-napkin auto-inits git on first session

Because distill.enabled is true and the vault has no .git/ yet, pi-napkin runs ensureVaultReadyForDistill at session start and automatically initializes the vault as a git repository:
  1. Runs git init -q -b main in the vault root.
  2. Installs the managed .gitignore block (delimited by # BEGIN NAPKIN-DISTILL MANAGED / # END NAPKIN-DISTILL MANAGED markers) that excludes .napkin/distill/, .obsidian/workspace*.json, .obsidian/cache, .obsidian/.trash/, and common secret patterns.
  3. Stages everything with git add . (respecting the just-written .gitignore) and creates an initial commit: napkin: initial vault commit (auto-distill setup).
After this completes, the vault is ready for worktree-based distillation. The auto-distill timer arms immediately and the distill: Xm..s countdown appears in the pi status bar.
When pi-napkin auto-initializes git on your first session, it posts a one-time notification with this information:
  • Initialized git repo in your vault for auto-distill.
  • Commit: 'napkin: initial vault commit (auto-distill setup)'
  • Files tracked: <N> — the count comes from countTrackedFiles, which runs git ls-files on the freshly committed vault
  • To undo: rm -rf <vault>/.git — removes git history; your notes are untouched
  • To opt out: set distill.enabled: false in vault config.json
Auto-distill (interval + shutdown) requires the subdir vault layout — config at <vault>/.napkin/config.json with "vault": { "root": ".." }. This is what napkin init creates by default. If your vault uses the legacy embedded layout (config at <vault>/config.json with no .napkin/ subdir), you will see a migration notification at session start and auto-distill will be disabled for that session. See the Migration guide for how to convert a legacy vault.

Build docs developers (and LLMs) love

Get started for freeTalk to us