Knotbook Extensions

The official extension catalog for Knotbook, a local-first notes app whose AI runs entirely on your machine.

Every extension here lives in its own folder under extensions/, was submitted by its author through a pull request, and was reviewed before being merged. Knotbook reads its catalog straight from this repository, so what you see here is exactly what the app offers to install.

Because all of it is public source, you can read what an extension does before you run it. There is no store backend, no accounts, and no telemetry. The only network request Knotbook makes for extensions is fetching this repository's registry.json and the files of an extension you chose to install — and only while you have the Extensions panel open.

How extensions work

A Knotbook extension is a folder with a manifest.json and the JavaScript it references. When you enable one, Knotbook runs its entry file in a Web Worker: no DOM, no filesystem, no fetch to your workspace, no access to the app's own internals. The worker's only channel to Knotbook is a knotbook object built from the permissions the manifest declared, where every method is a message the host answers.

That means two things worth knowing up front:

• Everything is a Promise. Reading a note is a round trip.
• There is nothing to draw on. An extension can register palette commands and open dialogs and notifications. It cannot inject UI into the app. If you need to show something rich, write it into a note and open it — that's what tag-report does.

Extensions install disabled. You enable them in the sidebar under Extensions, or in the manager, which also shows each one's permissions and a live log of its console output.

Repository layout

registry.json          the catalog Knotbook fetches (generated — don't hand-edit)
create.sh              scaffolds a new extension — macOS/Linux
create.bat             the same for Windows
cli/                   the `knotbook` CLI (scaffold, validate, vendor the UI Kit)
ui-kit/                the Knotbook UI Kit — interaction helpers for extensions
extensions/
  word-count/
    manifest.json
    main.js
    README.md

One folder per extension. The folder name must equal the id in its manifest.

Writing an extension

Fastest start, from the repo root:

# macOS / Linux
./create.sh --id my-extension --name "My Extension" \
  --description "What it does." --author "Your Name" \
  --permissions ui,editor

:: Windows
create.bat --id my-extension --name "My Extension" ^
  --description "What it does." --author "Your Name" ^
  --permissions ui,editor

Run the scaffolder with no arguments to be prompted for each field. It creates extensions/<id>/ with a manifest.json, a working main.js, and a README.md ready to fill in.

There's also a CLI. It isn't published to npm yet — run it from a clone:

node cli/knotbook.mjs new my-extension --author "Your Name"        # scaffold
node cli/knotbook.mjs new my-extension --author "Your Name" --ui   # + UI Kit
node cli/knotbook.mjs validate                                     # check them all
node cli/knotbook.mjs registry                                     # regenerate registry.json

Add --ui to either to start with the UI Kit already wired in.

Prefer starting from something real? Copy one of these:

• word-count — the minimal reference. One command, two permissions, no state.
• ai-outline — the reference for the host API: the local model, the live editor selection, stored settings, and a confirm before it overwrites anything.
• daily-digest — grounded AI answers filed as notes, including how to tell a grounded answer from an ungrounded one.
• tag-report — generates an index note and rewrites it in place on every run.
• related-notes — workspace search, with the results written back into the document.
• task-roundup — the pick-one-from-a-list pattern, spelled out.
• ui-kit-demo — every interaction the UI Kit provides.

For the complete guide — every API, every permission, worked examples — see DEVELOP.md.

The manifest

{
  "id": "word-count",
  "name": "Word Count",
  "version": "1.0.0",
  "description": "Reports the size of the note you have open.",
  "author": "Your Name",
  "homepage": "https://github.com/your-name",
  "entry": "main.js",
  "permissions": ["editor", "ui"],
  "assets": []
}

Field	Required	Meaning
id	yes	Unique identifier. Lowercase letters, digits, and hyphens. Must equal the folder name.
name	yes	Display name in the extension manager.
version	yes	MAJOR.MINOR.PATCH. Must increase on every update — a PR check enforces it.
description	yes	One or two sentences on what it does.
author	yes	Your name or handle.
entry	yes	The JavaScript file to run, relative to the folder.
homepage	no	Your site or profile.
permissions	no	Capability groups you need. Omitted means the extension can run but can't do anything.
assets	no	Extra files shipped beside the entry. A catalog install fetches exactly these, so anything not listed won't arrive.

Permissions

Each permission unlocks one group on the knotbook object. Anything you didn't declare simply isn't there, and calling it rejects with a message naming the scope you're missing.

Permission	Unlocks
notes	notes.list / read / byTitle — read notes.
notes:write	notes.create / save / rename / append — change them.
search	search.query — the workspace index.
editor	editor.* — the open document, the selection, insert and replace.
ai	ai.chat / complete / ask — the local model.
storage	storage.* — a private key/value store for your extension.
ui	ui.* — palette commands, notifications, dialogs, opening a note.
workspace	workspace.current / paths — which workspace is open.
tags	tags.list / notesFor.
tasks	tasks.list / toggle.

knotbook.on and knotbook.off need no permission — an extension that can't react to anything is inert.

Reading and writing notes are deliberately separate: most extensions only need to read, and a user looking at the permission list should be able to tell the difference at a glance. A manifest requesting an unknown permission is rejected by the PR check, and the manager strikes it through if one slips into an installed extension.

Submitting an extension

1. Fork this repository and branch off stable.
2. Scaffold or copy your extension into extensions/<id>/.
3. Fill in the folder's README.md: what it does, which permissions it needs and why, and what it touches. Users read this before enabling anything.
4. Run node cli/knotbook.mjs registry and commit the updated registry.json.
5. Open one pull request per extension, touching only your own folder plus registry.json.

The PR check enforces: one extension per PR, a valid manifest, id matching the folder, known permissions, every referenced file present and inside the folder, a README.md, a bumped version on updates, and a current registry.json.

Updates follow the same route — change the files, bump version, regenerate the registry.

Security and privacy

• Extensions run in a Web Worker with no DOM and no direct workspace access. Every capability goes through the host, which checks the declared permissions on each call.
• Nothing installs enabled. Nothing auto-updates.
• Installing from a local folder or a .knotplug file makes no network request at all. A catalog install fetches only that extension's declared files.
• The AI is the model already on your machine. No extension can send your notes anywhere; the host exposes no network capability of any kind.
• All of this is public source. Read it before you enable it — that's the whole reason the catalog is a git repository rather than a store.

Found a problem in an extension here? Open an issue on this repository. For a vulnerability in Knotbook itself, follow the app's SECURITY.md.