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.

pi-napkin works with existing Obsidian vaults out of the box. napkin detects the .obsidian/ directory and treats the parent directory as a vault root — no migration or restructuring required. The .napkin/ config directory lives alongside .obsidian/, keeping pi-napkin’s configuration separate from Obsidian’s own settings.

​
Connect an Existing Obsidian Vault

1

cd into the vault and run pi

Just change into your existing Obsidian vault directory and launch pi. napkin’s vault resolution walks up from your current working directory looking for .obsidian/ (among other vault indicators), so no extra flags or configuration are needed for basic use.
cd ~/Documents/my-obsidian-vault
pi
2

napkin-context detects and injects vault context automatically

On session start, the napkin-context extension resolves the vault and injects the vault overview into the agent’s context. The kb_search and kb_read tools are registered automatically, giving the agent read access to your notes from the first message.No .napkin/config.json is required for basic context injection — napkin detects .obsidian/ and works with defaults.

​
Enable Auto-Distill on an Existing Obsidian Vault

Auto-distill requires a .napkin/config.json with distill.enabled: true and a git repository. If your vault does not already have these, follow these steps:
1

Create .napkin/config.json if it doesn't exist

Create the .napkin/ subdirectory inside your Obsidian vault and add a minimal config.json:
mkdir -p .napkin

{
  "vault": { "root": ".." },
  "distill": {
    "enabled": true
  }
}
The "vault": { "root": ".." } entry tells napkin that the note root is the parent of .napkin/. This is the subdir layout that auto-distill requires.
2

Set distill.enabled: true

Ensure distill.enabled is set to true in .napkin/config.json. You can edit the file directly or use the napkin CLI:
napkin --vault . config set --key distill.enabled --value true
3

Start a pi session — pi-napkin prompts to auto-init git if needed

Launch pi from the vault directory. On session start, pi-napkin checks whether the vault is a git repository:
  • If the vault is not yet a git repo: pi-napkin automatically runs git init, installs the managed .gitignore block, and creates the initial commit (napkin: initial vault commit (auto-distill setup)). You’ll see a one-time notification with the file count and instructions to undo or opt out.
  • If the vault is already a git repo: pi-napkin just installs the managed .gitignore block (if not already present) and moves on. No new git init is needed.
pi

​
If Your Vault Is Already a Git Repo

Many Obsidian vaults double as project directories that are already tracked in git. pi-napkin handles this cleanly: it detects .git/, skips initialization, and only installs its managed .gitignore block if the block is not already present. Your existing git history, branches, and remotes are untouched. The managed block (delimited by # BEGIN NAPKIN-DISTILL MANAGED / # END NAPKIN-DISTILL MANAGED) adds entries for:
  • .napkin/distill/ — pi-napkin’s ephemeral per-worktree session fork directory
  • .obsidian/workspace*.json, .obsidian/cache, .obsidian/.trash/ — Obsidian workspace-local state
  • Common secret and cache files (.env, *.pem, *.key, .DS_Store, etc.)
Content outside the managed markers is user territory and is never touched.
The managed .gitignore block automatically excludes Obsidian workspace-local state files (.obsidian/workspace*.json, .obsidian/cache, .obsidian/.trash/). These files change frequently as you navigate your vault in Obsidian and would otherwise create noisy git diffs and conflict with distill commits. Your vault’s actual note content, plugins, and theme settings are tracked normally.
Project vaults work great with pi-napkin. When your Obsidian vault is also a project directory (for example, a repository for a software project where you keep design notes and decision logs), the vault is auto-detected from your current working directory when you run pi inside the project. This gives you a per-project knowledge base that distills conversation context directly into your project’s notes — no --vault flag needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us