pi-napkin has two components to install: theDocumentation 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.
@cad0p/napkin CLI (a standalone npm package that operates directly on Obsidian-compatible vaults) and the @cad0p/pi-napkin extension (a pi extension package that wires the CLI into your agent sessions). The CLI must be installed first because the extension shells out to it at runtime. Several system-level dependencies are also needed for the auto-distill feature — all of them are standard Unix tools.
Requirements
| Requirement | macOS | Linux | Notes |
|---|---|---|---|
| bash 4+ | brew install bash (macOS ships bash 3.2 by default) | Ships as bash in all major distros | The auto-distill wrapper uses bash arrays, local -n, and other bash-4 features. The wrapper resolves bash via #!/usr/bin/env bash. |
timeout(1) from coreutils | brew install coreutils (provides gtimeout) | Ships as timeout | Used to bound the agent’s wall-clock budget for each distill subprocess. The wrapper detects either timeout or gtimeout and falls back with a clear error if neither is present. |
| git 2.20+ | Ships as 2.39+ on Ventura+; or brew install git | Available via apt, dnf, pacman | Required for git worktree, merge-base --is-ancestor, and symbolic-ref --short HEAD. Needed only for auto-distill — manual /distill works without git. |
| pi with a model provider | pi install docs | pi install docs | Auto-distill spawns pi -p against the model in distill.model. Manual /distill reuses the parent session’s provider. |
Install the napkin CLI
Install@cad0p/napkin globally so the napkin binary is on your PATH:
Install the pi-napkin extension
With the napkin CLI installed, add the pi-napkin extension to your pi environment:napkin-context and napkin-distill) and the napkin skill with pi. The current stable release is 0.3.1.
Pre-release installs
Calver snapshots frommain are published to the @next tag on every push:
pi pins npm installs with an explicit tag or version. Running
pi update will not auto-bump a @next install to a newer snapshot. Re-run pi install npm:@cad0p/pi-napkin@next explicitly to pick up the latest pre-release build.Dev / source installs
To install directly from the GitHub repository (useful for testing unreleased changes or contributing):Verify the installation
Start a pi session from inside (or under) a directory with a napkin vault:📜 napkin— thenapkin-contextextension found a vault and injected the overview into the agent’s context.distill: off(ordistill: 59m00scounting down if auto-distill is enabled) — thenapkin-distillextension is loaded.
napkin --version works from your terminal (the CLI is on PATH) and that you’re running pi from a directory that resolves to a vault — either a directory with a .napkin/ subdir or any descendant of one.