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.
The napkin-context extension gives every pi session immediate awareness of your Obsidian-compatible knowledge vault. On each session start it resolves the vault from the current working directory, generates a vault overview, and injects that overview as a custom context entry into the session — so the agent always knows what your vault contains and how it’s organized before the first message. It also registers the kb_search and kb_read tools, which the agent can call at any point during a session to search for notes or read individual files.
Extension entry point
File: extensions/napkin-context/index.ts
The module’s default export is a function that receives the pi extension API and uses it to register all handlers and tools:
export default function (pi: ExtensionAPI) {
// registers message renderer, session_start handler, kb_search, kb_read
}
session_start handler
The handler fires once per session start (including session resume and fork). Its responsibilities are:
-
Resolve the vault — calls
new Napkin(ctx.cwd) to locate the vault from the current working directory. If vault resolution throws (no vault reachable from cwd), the handler returns early and no context is injected.
-
Generate the vault overview — calls
n.overview() internally to produce a multi-line text summary of the vault’s folder structure, keyword index, and note counts. Returns null when NAPKIN.md is absent or the vault is empty.
-
Inject context (idempotent) — before injecting, scans the existing session entries for any entry where
e.type === "custom_message" and customType === "napkin-context". If one already exists (resumed session), injection is skipped. Otherwise calls:
sm.appendCustomMessageEntry("napkin-context", content, true);
true) sets display: true, marking the entry as visible in the TUI.
-
Update the status bar — if the UI is available and
showStatus is enabled (see Config), sets the "napkin" status key:
- Vault found:
📜 napkin (the glyph is themed with theme.fg("dim", " napkin"))
- No vault / no
NAPKIN.md: napkin: no NAPKIN.md (themed dim)
ReadonlySessionManager cast — pi’s ExtensionContext narrows sessionManager to ReadonlySessionManager, which omits mutation methods. At runtime it’s always the full SessionManager, but if pi ever wraps the instance in a genuine readonly proxy the mutation method will either be absent or throw. The extension casts through Partial<SessionManager> before calling appendCustomMessageEntry:const sm = ctx.sessionManager as Partial<SessionManager>;
if (typeof sm.appendCustomMessageEntry === "function") {
sm.appendCustomMessageEntry("napkin-context", content, true);
}
Custom message renderer
Registered with:
pi.registerMessageRenderer("napkin-context", (message, { expanded }, theme) => { ... });
| State | Rendered output |
|---|
| Collapsed | 📜 napkin vault context — Ctrl+O to expand — label styled with theme.fg("customMessageLabel", "📜 napkin vault context"), hint styled with theme.fg("dim", " — Ctrl+O to expand") |
| Expanded | Full vault overview rendered as Markdown using pi-tui’s Markdown component, with all standard heading, link, code, blockquote, list, and inline-style tokens themed from the active color palette |
TextContent[] arrays (narrowing to text-only entries) so it is forward-compatible if pi ever stores image-bearing content in custom messages.
kb_search
Searches the knowledge base for notes matching a free-text query.
| Property | Value |
|---|
| Name | kb_search |
| Label | KB Search |
| Description | Search the knowledge base for notes matching a query |
| Prompt snippet | Search the napkin vault for notes by keyword or topic |
Type.Object({
query: Type.String({ description: "Search query" })
})
Free-text search query. Passed to napkin.search(query) which performs keyword and topic matching across all vault notes.
"No results found." when there are no matches.
The result renderer uses a collapsed view of up to 15 lines (maxCollapsedLines = 15) with a ... (N more lines, <key> to expand) hint when the result exceeds that.
kb_read
Reads a single file from the knowledge base by name or path.
| Property | Value |
|---|
| Name | kb_read |
| Label | KB Read |
| Description | Read a file from the knowledge base |
| Prompt snippet | Read a note from the napkin vault by name or path |
Type.Object({
file: Type.String({ description: "File name or path to read" })
})
File name or relative path to the note. Passed to napkin.read(file), which resolves the note within the vault.
maxCollapsedLines = 10) with the same expand hint as kb_search.
Config key: showStatus
The status bar glyph is controlled by the showStatus key in the vault’s config file:
<vault.configPath>/config.json
.napkin/config.json relative to the vault root.
| Value | Behavior |
|---|
true (default, also when file is absent) | Status bar entry is displayed |
false | Status bar entry is suppressed entirely |
session_start time via loadShowStatus(vault.configPath). Missing file or missing key both default to true.
Peer dependencies
From package.json:
| Package | Version constraint | Role |
|---|
@earendil-works/pi-coding-agent | >=0.74.0 | ExtensionAPI, SessionManager, Theme, tool/renderer registration |
@earendil-works/pi-tui | >=0.74.0 | Markdown, Text TUI components for rendering |
@sinclair/typebox | ^0.34.49 | TypeBox Type.Object / Type.String for tool parameter schemas |