{"id":49882657,"url":"https://github.com/raphapr/pi-zk","last_synced_at":"2026-05-15T16:01:48.468Z","repository":{"id":357008697,"uuid":"1234955912","full_name":"raphapr/pi-zk","owner":"raphapr","description":"Talk to your Zettelkasten from Pi","archived":false,"fork":false,"pushed_at":"2026-05-10T22:00:22.000Z","size":95,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-10T23:29:37.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raphapr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T21:20:08.000Z","updated_at":"2026-05-10T22:02:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raphapr/pi-zk","commit_stats":null,"previous_names":["raphapr/pi-zk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/raphapr/pi-zk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphapr%2Fpi-zk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphapr%2Fpi-zk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphapr%2Fpi-zk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphapr%2Fpi-zk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raphapr","download_url":"https://codeload.github.com/raphapr/pi-zk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raphapr%2Fpi-zk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33071582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-15T16:01:00.076Z","updated_at":"2026-05-15T16:01:48.463Z","avatar_url":"https://github.com/raphapr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-zk\n\nA [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.\n\n## What you get\n\nTwelve 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.\n\n```text\n[user]\u003e What did I write last week tagged #work but not yet linked to my OKR note?\n\nzk_search_notes  \"tag:work modified-after:1 week ago\"\nzk_linked_by     \"okrs/2026-Q2.md\"\n…\n```\n\n## Install\n\n```bash\npi install git:github.com/raphapr/pi-zk\n```\n\nRequirements:\n\n- [`zk`](https://github.com/zk-org/zk) **0.15** or newer on `PATH`\n- An initialised zk notebook (`zk init` in your notes directory)\n\n## Tools\n\n| Tool               | Purpose                                                                       |\n| ------------------ | ----------------------------------------------------------------------------- |\n| `zk_search_notes`  | Filter notes by FTS query, tags (AND/OR/NOT), paths, and date ranges          |\n| `zk_read_note`     | Read a note's full content by notebook-relative path                          |\n| `zk_create_note`   | `zk new` wrapper; auto-creates nested directories and can prepopulate content |\n| `zk_edit_note`     | Exact-match text replacement with uniqueness enforcement                      |\n| `zk_append_note`   | Append a markdown block with blank-line normalisation                         |\n| `zk_list_tags`     | List every tag with note counts                                               |\n| `zk_link_to`       | Backlinks for a note (supports recursive traversal + max-distance)            |\n| `zk_linked_by`     | Notes a given note points to (supports recursive traversal)                   |\n| `zk_related`       | Notes that share neighbours but are not yet linked                            |\n| `zk_last_modified` | Most recently edited note, optionally tag-filtered                            |\n| `zk_tagless_notes` | Notes with no tags (useful for triage)                                        |\n| `zk_random_note`   | One random note, optionally tag-filtered                                      |\n\nAll tools accept an optional `notebook` parameter that overrides env-based resolution for a single call.\n\n## Wikilink autocomplete\n\nTyping `[[` in the Pi editor surfaces a fuzzy-ranked menu of notes from the active notebook:\n\n```text\nsee [[zett▎       zettelkasten   — Zettelkasten  #theory\n                  2026-05-09     — Weekly review #work #deep\n                  …\n```\n\n- Match runs across filename stem, title, and tags\n- Suggestions are capped at 20\n- The cache indexes the 500 most recently modified notes by default\n- Set `ZK_AUTOCOMPLETE_LIMIT` to raise or lower the indexed-note cap (maximum 5000)\n- Notes are cached per notebook with a 60-second TTL\n- Cache is invalidated automatically after `zk_create_note`, `zk_edit_note`, and `zk_append_note`\n\n## System prompt guidance\n\nWhen 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.\n\n## Configuration\n\nNotebook resolution checks in order:\n\n1. `ZK_NOTEBOOK_DIR` environment variable\n2. `ZK_DIR` environment variable\n3. The current working directory if it contains `.zk/`\n4. The nearest ancestor of the cwd that contains `.zk/`\n\nOther env vars:\n\n- `ZK_BIN` — explicit path to the `zk` binary (defaults to `~/.local/bin/zk`, then `zk` on `PATH`)\n- `ZK_AUTOCOMPLETE_LIMIT` — number of recent notes indexed for wikilink autocomplete (default 500, maximum 5000)\n- `ZK_EDITOR`, `EDITOR`, `VISUAL` — forced to `true` during `zk_create_note` so non-interactive notes are created without launching your editor\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\n```\n\nThe 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.\n\nLoad the extension without publishing:\n\n```bash\npi -e /path/to/pi-zk/src/index.ts\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphapr%2Fpi-zk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraphapr%2Fpi-zk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphapr%2Fpi-zk/lists"}