pi-note

npm · Pi package directory

Shared Pinote tasks and Markdown handoffs in Pi. A dedicated extension connects directly to an authenticated MCP Streamable HTTP service. No MCP gateway, VM-local Python installation, or network-mounted database is needed.

Host Pi ── Pinote extension ──┐
                             ├─ HTTPS → Pinote service → notes.db
VM Pi ──── Pinote extension ──┘

Tasks, tags, progress and handoff fields are shared. Selection and pending suggestions belong to each Pi conversation/branch, not the HTTP connection. Other tools continue running wherever Pi and their services run.

Install

Requires Pi 1.4.0+ and Node.js 22.19+. The service additionally needs Python 3.11+ and note 0.12.0+. Install and start the Pinote service first, then on each client:

pi install npm:pi-note
# Or, from a checkout:
pi install ./pi

Set the endpoint and use the same private bearer token as the service before starting Pi. Both read PINOTE_TOKEN, or a private owner-only PINOTE_TOKEN_FILE (default <Pi agent directory>/pinote-token):

export PINOTE_URL=https://notes.example.net/mcp
# Load PINOTE_TOKEN from your private environment/secret manager; never commit it.
pi

The token must contain at least 32 non-whitespace characters. The default endpoint is http://127.0.0.1:8765/mcp. Non-loopback HTTP requires the explicit PINOTE_ALLOW_HTTP=1 opt-in and a trusted private VPN; prefer HTTPS. Endpoint URLs cannot contain credentials, query strings or fragments. Do not register this service again through Pi's built-in MCP client: the extension owns the connection, state routing, tools and UI.

Use

Open /pinote. Select or create a task, preview it, clear the selection, complete it, respond to suggestions, or edit shared settings. Selecting an existing task starts it immediately and returns focus to the prompt, with no extra confirmation. Creation and settings changes still require confirmation. Nothing submits a model prompt automatically; inserting Continue's draft requires confirmation and preserves an existing draft.

Menus use Pi's native components and configured selection keys. Escape goes back; Ctrl+R refreshes. Settings with fewer than five choices cycle inline. Fullscreen has a native clickable footer: ▤ opens Pinote; clicking a selected title previews it and double-clicking completes it. A suggested title requires a double-click to accept. Regular mode shows status; /pinote provides all actions. No Kitty action handler is needed for this extension.

Completion keeps the conversation and editor, except for dedicated Start in Kitty… sessions (see below). With an empty editor, Ctrl+D (or your configured exit key) offers Cancel, Exit without completing, or Complete task and exit. /new offers Cancel, Start new session without completing, or Complete task and start new session. With no selected task, /new proceeds normally. Completion requires idle Pi and a current displayed revision; failures keep the current session open. /quit exits without completing.

Reload/resume restores the active branch's selection. Starting a new session without completing retains the selection; completing starts it unselected. Unrelated fresh launches start unselected. Changing endpoints starts a separate selection namespace. Unsaved Pi sessions cannot guarantee selection persistence.

The GTK app's Start in Kitty… action (note 0.13.0+) chooses a working directory and opens a named tab with this task selected, without submitting a prompt. In note 0.16.0+, it uses the tag's default folder when available, otherwise keeps the directory chooser. Set or clear defaults in Manage tags…. With note 0.15.0+ and pi-note 0.32.0+, successful selection prefills an empty Pi editor with is task clear?. Configure gui.kitty_start_prompt in the GUI config, or set it to "" to disable; existing drafts are never replaced. The service needs pi-note 0.31.0+. The one-shot PINOTE_LAUNCH_TASK environment handoff carries the task ID, displayed revision and optional editor draft, never task text or tokens. The draft stays client-local and is never sent to the service or persisted as launch state. Only a fresh session can consume it. The service must share the GUI's database; missing/stale revisions fail closed. Resume, reload and /new never replay the handoff or replace another selection. Pi keeps its normal endpoint/token settings. With pi-note 0.33.1+, completing the launched task from the menu, footer or Complete task and exit runs git pull --ff-only --no-rebase --no-autostash in Pi's working directory before exiting, so Kitty closes its dedicated tab (or the standalone window's last tab). It never merges, rebases or stashes local changes. If Git fails, times out (30 seconds), or the session/draft changes, Pi stays open; the task remains completed and is not retried. Check Git manually, then /quit. Non-Git directories or branches without an upstream also stay open after the failed pull. /quit and Exit without completing do not pull. This ownership survives /reload, but not /new, resume, fork, tree navigation or process restart. Completing a different task or an externally completed task does not pull or close Pi; failed/uncertain completion stays open.

Agent tools and context

The extension registers pinote_search, pinote_get_task, pinote_get_current, pinote_update_current, pinote_fields, pinote_tags, and pinote_propose. Default guidance suggests tasks only for substantial work requiring changes, not questions, explanations, research, read-only inspection, or trivial edits. Suggestions do not create/start/select tasks until accepted in the UI. Reads by ID do not change selection. Updates require the task's expected_updated_at revision; concurrent edits are rejected rather than overwritten.

Fresh selected-task context and service guidance are read before every agent run. Task text and handoff fields are untrusted data, not authorization. Failed reads explicitly report unavailable context; they never reuse a cached task or claim no task is selected. Tool results and injected context can reach your configured model: do not put secrets in tasks.

External CLI/GTK/client edits refresh connected views through notifications. After a network failure, use /pinote or a tool call to reconnect. Mutations are never automatically replayed: a failed write may already have committed, so read fresh state before retrying. Server restart loses HTTP sessions, not notes. There is no offline write queue or database replication.

Shared settings

Settings live in pi-note.json on the service machine, under its PI_CODING_AGENT_DIR (default ~/.pi/agent). The Pinote app edits prompts, injected agent guidance and footer definitions with confirmation and revision checks. A malformed configuration fails closed; fix it on the server rather than replacing it with defaults. Task fields such as PR, Worktree and Next remain task data, separate from global display settings.

Migration

Since pi-note 0.33.0, /pinote is the only slash command in both modes. The /pi-note alias is removed; update saved shortcuts to /pinote. The npm package name and pi-note.json configuration filename are unchanged.

1. Back up the service machine's Pinote data; keep notes.db local to that machine.
2. Start the standalone service against that same database and settings directory.
3. Remove Pinote's service entry and its unused package entry from the gateway configuration; preserve all other services/packages.
4. Remove the old gateway-dependent exit-confirm.ts companion and any old local index.ts extension from Pi's load list. Load this package once.
5. Finish active gateway jobs before reloading Pi. Configure each VM client with the remote endpoint and token, then select its task in /pinote.

Existing gateway selection entries are not imported; notes and handoff fields are unchanged. Remote-safe Ctrl+D handling is built into this extension; the obsolete gateway companion is removed. The existing local-only CLI extension remains available explicitly for on-device use, but must not be loaded alongside the HTTP extension.

Development and releases

From the repository root:

uv sync --locked
npm --prefix pi ci --ignore-scripts
npm --prefix pi test
(cd pi && npm pack --dry-run)

Tests use the checkout's own .venv/bin/note, real HTTP/stdio servers and temporary storage. UI validation must use Xvfb, a private D-Bus session and temporary app data.

The npm and Python packages are versioned independently. Bump npm with npm version patch|minor|major --no-git-tag-version inside pi/ and commit its manifest and lockfile together. GitHub CI tests main, then publishes new npm versions through OIDC trusted publishing; registry failures fail the workflow. The trusted publisher is kvidzibo/pinote, workflow publish.yml, no environment. Installation never edits personal Pi, shell, systemd or desktop configuration.