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 registers tools directly with the pi agent’s tool system, making them available during LLM conversation turns. Unlike slash commands (which you invoke explicitly), agent tools are called autonomously by the model when it determines they are relevant — for instance, searching the vault before writing a new note, or checking for in-flight distills before editing a file. The tools are registered at session start alongside the vault overview context injected by the napkin-context extension.
Search the knowledge base for notes matching a query string. Name: kb_search · Label: KB Search The distill prompt explicitly instructs the agent to call kb_search before creating any new note, to avoid duplicating content that already exists in the vault. Use this tool proactively whenever you are working on a topic that may already be covered.

​
Parameters

The TypeBox schema for this tool is: 
Type.Object({
  query: Type.String({ description: "Search query" })
})
​
query
string
required
The search query. Can be a keyword, phrase, or topic description. The underlying napkin search command performs a full-text search across all indexed vault notes.

​
Returns

A list of matching notes. Each result contains the vault-relative file path and one or more text snippets showing where the query matched. 
[
  {
    "file": "auth/oauth-flow.md",
    "snippets": [
      { "text": "OAuth 2.0 flow with PKCE for CLI tools" }
    ]
  },
  {
    "file": "patterns/api-client.md",
    "snippets": [
      { "text": "Standard patterns for REST API clients" }
    ]
  }
]
When no notes match, the tool returns "No results found." as a plain text response.

​
UI rendering

Results are shown collapsed by default (15 lines maximum, maxCollapsedLines = 15). Press Ctrl+O to expand the full output. File names are rendered in bold with snippet text indented below.

​
When to use

Always call kb_search before creating a new note on a topic. If a matching note already exists, use napkin append to add to it rather than creating a duplicate. The distill agent’s system prompt enforces this pattern — your interactive sessions should follow the same convention to keep the vault free of redundant entries.

​
kb_read

Read the full content of a specific note from the knowledge base. Name: kb_read · Label: KB Read

​
Parameters

The TypeBox schema for this tool is: 
Type.Object({
  file: Type.String({ description: "File name or path to read" })
})
​
file
string
required
The file name or vault-relative path of the note to read. Accepts both bare filenames (oauth-flow.md) and paths with directories (auth/oauth-flow.md).

​
Returns

The full markdown content of the note as text, plus the resolved file path in the tool’s details field. 
kb_read("auth/oauth-flow.md")
# Returns the full markdown content of that note
The resolved path is surfaced in the tool result’s details object as path, allowing callers to confirm which file was actually read when a bare filename matched multiple candidates.

​
UI rendering

Results are shown collapsed by default (10 lines maximum, maxCollapsedLines = 10). Press Ctrl+O to expand the full note content.

​
napkin_distill_status

Query the live status of background distill subprocesses and unmerged distill branches for the current vault. Name: napkin_distill_status · Label: Napkin distill status This tool is the programmatic equivalent of the /distill-status slash command. It returns the same data as structured JSON, making it suitable for agent decision-making. The primary use case is checking whether a background distill is currently writing to the vault before the agent makes its own edits to vault files.

​
Parameters

This tool takes no parameters — its TypeBox schema is Type.Object({}) (empty object).

​
Returns

When no vault is resolvable from the current directory, the tool returns an error payload: 
{ "error": "no vault in cwd" }
When a vault is resolved, the tool returns the output of distillStatusToJson(active, unmerged):
​
active
array
List of active distill subprocesses detected from the vault’s git worktree registry and meta.json sidecars. Each entry is serialized from ActiveDistill via distillStatusToJson.
​
unmerged
string[]
List of distill/* branch names that exist in the vault’s git repo but have no live worktree. These are orphaned branches from crashed or incomplete distills. They are candidates for cleanup and are automatically pruned by the full-level health check after a 24-hour grace period.

​
Example response

{
  "active": [
    {
      "pid": 12345,
      "branch": "distill/abc123-1715198400",
      "elapsedSeconds": 45,
      "session": "session-abc.jsonl",
      "alive": true,
      "startedAt": "2024-05-08T14:00:00.000Z",
      "startSha": "abc1234567890"
    }
  ],
  "unmerged": ["distill/xyz456-1715184000"]
}

​
When to use

If active contains any entry with alive: true, a background distill is currently writing to the vault. Concurrent agent writes to the same note paths may be overwritten or create merge conflicts that the distill wrapper’s post-validation step will surface as a failed:markers-after-agent-exit outcome.
Call napkin_distill_status before making edits to vault files when:
  • You are in a session with distill.enabled: true and the interval timer may have fired recently.
  • You are running multiple concurrent pi sessions against the same vault.
  • You have just received an overlap notice (⚠️ Background napkin distill is editing files you've also touched) and want to confirm the distill has finished before continuing.
If active is non-empty with alive: true, consider waiting for the distill to complete (the worktree path disappears when done) or editing a different note path that does not overlap with the distill’s branch.

Build docs developers (and LLMs) love

Get started for freeTalk to us