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.
/distill slash command lets you trigger knowledge capture immediately, on your own schedule. Unlike auto-distill, which fires on a timer, /distill runs right now — no waiting for the next interval. It works on any vault and does not require git or distill.enabled: true, making it the right tool when you want to capture a specific piece of work, run a one-off capture on a git-less vault, or override the deduplication check to force a fresh distill.
Using /distill
Type/distill in any pi session. The command checks whether a distill is already running, then routes to either the worktree path (concurrent-safe) or the legacy tmpdir path (simpler, no git side effects), depending on your vault’s configuration.
Before triggering
/distill, run /distill-status to confirm no distill is already in progress. If one is running, /distill will notify you and exit — it won’t spawn a second concurrent process.Routing logic
The path/distill takes depends on three factors: whether git is present in the vault, whether distill.enabled is true, and whether the vault uses the subdir layout.
| Condition | Path taken | Concurrency safety |
|---|---|---|
git present AND distill.enabled: true AND subdir layout | Worktree path — same as auto-distill | ✅ Concurrent-safe via per-distill git worktrees |
git absent OR distill.enabled: false OR legacy embedded layout | Legacy tmpdir path — no git side effects | ⚠️ No concurrency coordination |
distill.enabled: false means the user has opted out of auto-distill’s git infrastructure. The legacy path bypasses worktrees, managed .gitignore, and session-fork housekeeping entirely — useful for quick captures on vaults where you don’t want any git involvement.
Worktree path
When all three conditions are met,/distill runs the same full health check that auto-distill runs before each interval tick. Auto-recovered findings (managed .gitignore block drift, untracked config file) surface as info notifications and the distill proceeds. Error findings (malformed config, legacy embedded layout, .napkin/config.json gitignored) abort the spawn and surface an error notification instead.
On success, a per-distill git worktree is created under ~/.cache/napkin-distill/<vault-hash>/, the session is forked into it, and a detached wrapper subprocess runs the full distill → merge → squash → push → cleanup lifecycle. The worktree path is concurrent-safe: multiple pi sessions running /distill simultaneously on the same vault each get their own isolated worktree and integrate through the agent’s own merge resolution.
Legacy path
When git is absent,distill.enabled is false, or the vault uses the legacy embedded layout, /distill falls back to a simpler spawn:
Spawn detached pi -p
Launches a detached
pi -p subprocess with the legacy distill prompt (steps 1–5: overview, templates, identify, search/create/append, daily note and supersedes frontmatter)./distill calls on a git-less or disabled vault will race on napkin writes. If this matters, use auto-distill with the subdir layout, which serializes through per-distill worktrees.
Status bar
While/distill is running, the status bar shows:
| State | Status bar |
|---|---|
| Running | ● distill (with elapsed seconds updating every 2s) |
| Completed successfully | ✓ distill Xs |
| Completed with warning | ⚠ distill: local-only / ⚠ distill: no content |
| Failed | ✗ distill: <reason> |
<vault>/.napkin/distill/errors/<timestamp>-<pid>-<branch>.outcome). The first line of the sidecar is a machine-readable class string that drives the UI severity. On the legacy path, the poller uses tmpdir disappearance as the sole completion signal and always shows a generic success notification.
Size deduplication
Both paths track the byte size of the session file at the last successful distill spawn. If the session file hasn’t grown since the last distill, the command resets the timer but does not spawn a new subprocess — there’s nothing new to capture./distill bypasses this check. When you run /distill manually, the command sets lastSessionSize = 0 before routing, so the size check always passes and the distill always spawns. This lets you force a re-distill even if the session hasn’t changed — useful after correcting a note manually or when you want to capture a specific window of work.
Use
/distill-status to check whether a distill is already running before triggering another. The command shows active worktrees, their PIDs, elapsed time, and unmerged branches for the current vault. The napkin_distill_status agent tool returns the same information as JSON, for use inside automated workflows.