pi-zk

A Pi extension that exposes the zk note-taking CLI as agent-native tools. Talk to your Zettelkasten from Pi.

What you get

Twelve LLM-callable tools wrapped around zk, plus wikilink autocomplete in the Pi editor and an automatic system-prompt nudge that routes note operations through the right tools.

[user]> What did I write last week tagged #work but not yet linked to my OKR note?

zk_search_notes  "tag:work modified-after:1 week ago"
zk_linked_by     "okrs/2026-Q2.md"
…

Install

pi install git:github.com/raphapr/pi-zk

Requirements:

• zk 0.15 or newer on PATH
• An initialised zk notebook (zk init in your notes directory)

Tools

Tool	Purpose
zk_search_notes	Filter notes by FTS query, tags (AND/OR/NOT), paths, and date ranges
zk_read_note	Read a note's full content by notebook-relative path
zk_create_note	zk new wrapper; auto-creates nested directories and can prepopulate content
zk_edit_note	Exact-match text replacement with uniqueness enforcement
zk_append_note	Append a markdown block with blank-line normalisation
zk_list_tags	List every tag with note counts
zk_link_to	Backlinks for a note (supports recursive traversal + max-distance)
zk_linked_by	Notes a given note points to (supports recursive traversal)
zk_related	Notes that share neighbours but are not yet linked
zk_last_modified	Most recently edited note, optionally tag-filtered
zk_tagless_notes	Notes with no tags (useful for triage)
zk_random_note	One random note, optionally tag-filtered

All tools accept an optional notebook parameter that overrides env-based resolution for a single call.

Wikilink autocomplete

Typing [[ in the Pi editor surfaces a fuzzy-ranked menu of notes from the active notebook:

see [[zett▎       zettelkasten   — Zettelkasten  #theory
                  2026-05-09     — Weekly review #work #deep
                  …

• Match runs across filename stem, title, and tags
• Suggestions are capped at 20
• The cache indexes the 500 most recently modified notes by default
• Set ZK_AUTOCOMPLETE_LIMIT to raise or lower the indexed-note cap (maximum 5000)
• Notes are cached per notebook with a 60-second TTL
• Cache is invalidated automatically after zk_create_note, zk_edit_note, and zk_append_note

System prompt guidance

When a notebook is detected at session start, pi-zk appends a short routing block to the system prompt so the LLM knows to prefer zk_* tools over generic read / edit / bash on note files. When no notebook is in scope the block is omitted.

Configuration

Notebook resolution checks in order:

1. ZK_NOTEBOOK_DIR environment variable
2. ZK_DIR environment variable
3. The current working directory if it contains .zk/
4. The nearest ancestor of the cwd that contains .zk/

Other env vars:

• ZK_BIN — explicit path to the zk binary (defaults to ~/.local/bin/zk, then zk on PATH)
• ZK_AUTOCOMPLETE_LIMIT — number of recent notes indexed for wikilink autocomplete (default 500, maximum 5000)
• ZK_EDITOR, EDITOR, VISUAL — forced to true during zk_create_note so non-interactive notes are created without launching your editor

Development

npm install
npm run typecheck
npm test

The test suite includes integration tests that exercise the real zk binary. They auto-skip when zk is not installed; install zk locally to run the full suite.

Load the extension without publishing:

pi -e /path/to/pi-zk/src/index.ts

License

MIT — see LICENSE.