---
slug: "pi-zk"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/raphapr/pi-zk@main/README.md"
repo: "https://github.com/raphapr/pi-zk"
source_file: "README.md"
branch: "main"
---
# pi-zk

A [Pi](https://github.com/mariozechner/pi-coding-agent) extension that exposes the [zk](https://github.com/zk-org/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.

```text
[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

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

Requirements:

- [`zk`](https://github.com/zk-org/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:

```text
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

```bash
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:

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

## License

MIT — see [LICENSE](https://github.com/raphapr/pi-zk/tree/HEAD/LICENSE).