Pine 0.13.0 · Documentation

Set up Pine 0.13.0

Private repository access is required. Sign in to GitHub CLI with gh auth login using an account that can read johnlindquist/pine. Pine uses that existing sign-in when downloading a private renderer release; credentials stay inside GitHub CLI.

Pine puts notes, tasks, widgets and saved custom agents beside Pi in herdr. Pi is the coding agent; herdr keeps Pi and its views in terminal panes. This guide covers macOS and Linux. Run one command at a time and stop at an unexpected error. Shell blocks go in a terminal. Commands beginning with / go inside Pi. Keep the user's existing Pi launcher, settings and project files.

When to use this guide

Use it when a person asks you to install Pine, recover a broken setup, or verify that notes and tasks work beside Pi in a chosen project. Read the whole guide before changing the environment. Built-in views and setup checks need no model call. Model access for conversations and builders is a separate step.

Pine runs locally inside Pi. There is no sign-in or remote installation endpoint. A read-only Pine API and MCP server returns these steps, the latest release and its checksums as JSON. Never send credentials or project content to this site. After setup, use Pine's installed local tool schemas and agent instructions to discover supported operations. For feature guides, start with the Pine documentation.

1. Check the chosen project and tools

Start in the project the user chose. Keep this shell open through step 5. Record these results; a missing Pi or herdr is expected on a fresh machine:

pwd
PINE_PROJECT="$(pwd -P)"
uname -s
uname -m
node --version
npm --version
git --version
command -v curl
command -v pi
command -v herdr

Use Node 22.19.0 or newer for Pi 1.4.0. Pine core alone supports Node 22.18+. If Node/npm is missing or too old, use the official installer or your existing version manager, then repeat the checks: https://nodejs.org/en/download. The exact Node 22.19.0 downloads are at https://nodejs.org/en/download/archive/v22.19.0. Select the OS and architecture reported above; Apple silicon uses the macOS arm64 build. Git is needed for the private Pine source; curl is needed for herdr's installer. Use the machine's existing package manager if either is missing. If download or installation is unavailable, report the failed command and exact error.

2. Add Pi if needed

Check an existing Pi before changing it:

pi --version

If that reports 1.4.0 or newer, keep it. For a new installation, run:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.4.0
pi --version

Expected for this pinned command: 1.4.0. If npm reports a permissions error, use this user-owned prefix, then check which executable will run:

npm install -g --ignore-scripts --prefix "$HOME/.local" @earendil-works/pi-coding-agent@1.4.0
export PATH="$HOME/.local/bin:$PATH"
command -v pi
pi --version

Keep the PATH entry in the user's shell configuration if needed. Do not use sudo or replace an existing custom launcher. Use that same Pi command and PI_CODING_AGENT_DIR for registration and interactive sessions.

3. Add herdr if needed

Check an existing installation first:

herdr --version

Pine 0.13.0 supports live herdr servers 0.9.3 (protocol 22) and 0.9.5. The CLI version alone does not identify a running server; step 6 checks both. If herdr is missing, the official macOS/Linux installer selects the platform, verifies its SHA-256 and writes to ~/.local/bin:

curl -fsSL https://herdr.dev/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
command -v herdr
herdr --version

The installer follows the stable channel, so record the actual version instead of assuming a pin. The reference environment uses 0.9.5. If installation fails, stop and preserve the error. A new CLI does not replace an already running server; save work before restarting herdr when doctor reports incompatibility. For an exact 0.9.5 binary, use this alternative instead of the stable installer. Select both values from this release table. Linux/macOS assets are bare executables; do not unzip them.

This example is Linux x86_64. Replace its first two values together for another machine. Stop if the checksum command fails; never copy a mismatched binary.

PINE_HERDR_ASSET=herdr-linux-x86_64
PINE_HERDR_SHA256=14d9e8bc8b4a9e0118d77c32266f76d461f09b40342eb23752960bd89f59929d
PINE_HERDR_TEMP="$(mktemp -d)"
curl -fL --retry 3 "https://github.com/herdrdev/herdr/releases/download/v0.9.5/$PINE_HERDR_ASSET" -o "$PINE_HERDR_TEMP/herdr"
node -e "const fs=require('node:fs'),crypto=require('node:crypto');const hash=crypto.createHash('sha256').update(fs.readFileSync(process.argv[1])).digest('hex');if(hash!==process.argv[2])throw Error('SHA-256 mismatch');console.log('SHA-256 verified: '+hash)" "$PINE_HERDR_TEMP/herdr" "$PINE_HERDR_SHA256"
chmod 755 "$PINE_HERDR_TEMP/herdr"
mkdir -p "$HOME/.local/bin"
cp -n "$PINE_HERDR_TEMP/herdr" "$HOME/.local/bin/herdr"
export PATH="$HOME/.local/bin:$PATH"
herdr --version

Expected: the digest matches and herdr reports 0.9.5. The copy does not overwrite an existing executable. If the version differs, inspect the path from step 1 instead of replacing another installation automatically.

4. Add one Pine source to the same Pi setup

Pine is a private GitHub repository. Sign in with repository access before installing. Keep GitHub CLI signed in for verified renderer downloads. Choose one source. The GitHub command pins the version shown in this tour:

pi install git:github.com/johnlindquist/pine@v0.13.0
pi list

Expected: the configured source includes github.com/johnlindquist/pine@v0.13.0. If Pine is already registered from another source, inspect that entry before adding a second one. Do not load a local copy and a Git copy together.

For a supplied local checkout, use this alternative from the chosen project. Replace only the path assigned to PINE_PACKAGE with the checkout's absolute path. Its directory must contain Pine's package.json:

PINE_PACKAGE=/absolute/path/to/pine
node -p "require(process.argv[1]).version" "$PINE_PACKAGE/package.json"
pi install "$PINE_PACKAGE"
pi list

Expected: the version check reports 0.13.0; pi list shows that exact absolute path. A local package loads in place, so keep the checkout there. No project dependency installation is needed for Pine core. Registration alone does not prove the extension, skill or renderer works; continue through step 6.

5. Start Pi inside herdr in the project

In the outer shell from step 1, return explicitly to the selected project:

cd "$PINE_PROJECT"
pwd
herdr

On herdr's first run, a welcome screen covers the shell. Press Enter at its Continue prompt. Finish or skip the optional agent-integration choices until the shell is visible; those integrations are not required for Pine. Do not send Pi commands while a herdr welcome or integration screen still covers the pane.

In herdr's new shell pane, check that pwd still names the selected project, then start Pi with no inherited Node options:

pwd
env -u NODE_OPTIONS pi

If this shell is in a different folder, change to the project's absolute path before starting Pi. Use the user's usual Pi launcher in place of pi if they have one. Let the user answer Pi's project-trust prompt for a project they trust. If trust was declined, restart Pi there to reconsider it. Do not grant trust by editing settings. In an already running Pi session, reload the added package:

/reload

Then check that the Pine guide appears:

/pine help

If Pine is unknown, check the package list in the same Pi settings environment and restart or reload. Do not type /pine commands into the shell. If Enter only accepts an autocomplete suggestion, press Enter again to run it.

6. Verify the actual panes and version

Inside Pi, type one command at a time and inspect each result:

/pine doctor --json
/pine open notes
/pine open tasks --popout
/pine status
/pine doctor

The first command shows the full diagnostic record; it can extend beyond one screen. Scroll through it to find the package value 0.13.0 and the other checks, then return to the prompt before typing the next command. Ordinary doctor output is only a short summary such as "Pine doctor: all 11 checks pass." The number can change as more features start. Success requires all of these observations:

• The full doctor record has no failed checks and its package value is 0.13.0.
• That record reports the Pine skill loaded, the project trusted and the live herdr server compatible. A healthy outside-herdr check is insufficient.
• Notes and tasks visibly render and are named. Empty lists are fine; a blank pane, an error or only a successful package registration is not success.
• Status describes those two verified panes. On a fresh wide tab Pi stays left and the views stack right. Below 104 columns the first view opens below Pi. Existing hand-arranged tabs keep their arrangement. F6 cycles focus.

The first view downloads the matching renderer and verifies SHA-256. If that fails, preserve the message and retry after connectivity returns. For a supplied local checkout, the source-build alternative needs Go 1.25.5 or newer:

go version
node "$PINE_PACKAGE/bin/pine.mjs" build

Run those in a shell, then retry the two view commands in Pi. The absolute path avoids building from the wrong project directory. Generated agent scripts also support macOS's built-in bash 3.2; a newer Bash is not a setup requirement.

For PINE_SKILL_MISSING, reload the package; if the parent Pi inherited NODE_OPTIONS, restart it using the clean launch from step 5. Directory-watch silence is handled by polling and is not a reason to delete state. For uncertain pane ownership or malformed records, preserve state and report the doctor error. Pine must not close unverified panes or recreate a damaged store.

7. Connect a model and finish

Notes, tasks, help and setup checks need no model call. Conversations and builders need a configured model. The user can use these Pi commands and keep existing credentials:

/login
/model

An account subscription or provider usage charges depend on the chosen model. Pi also supports local providers; a paid model is not required for the built-in views. Never ask the user to paste credentials into chat.

Only after step 6 passes, tell the user: "Pine 0.13.0 is ready in this project: notes and tasks opened inside herdr, and /pine doctor passed. Use /pine for the menu." Report the observed Node/Pi/herdr/Pine versions, the project path, model status and any PATH change. If model access is not configured, say so separately. If a required check is blocked, report its exact error and next action instead of using the completion sentence.

Optional: browser dashboard and shell shortcut

On macOS, Pine opens Google Chrome. On Linux, set PINE_BROWSER before starting Pi to an absolute executable launcher that opens its single URL argument and exits. Put any browser flags in that launcher, not in the variable. The terminal setup above does not require a browser. Once configured, use this inside Pi:

/pine dashboard

Choose a note or task, then Send selection. Confirm Pi says "Reference added to draft" and inspect the unsent draft. A page saying queued is not proof Pi accepted it. The optional pine shell shortcut is separate from package registration:

/pine install-command

Follow the returned PATH instructions. Skip this command if the shortcut is not wanted; the ordinary Pi commands remain available.

Uninstall while keeping work

When the user asks to remove Pine, close this session's verified views in Pi:

/pine close all

In a shell using the same Pi settings environment, inspect the configured source. For the pinned GitHub source above:

pi list
pi remove git:github.com/johnlindquist/pine@v0.13.0
pi list

For the local source above, use this instead:

pi remove "$PINE_PACKAGE"
pi list

Use the exact source shown by the package list if it differs. If it was added with project-local scope, remove it with that same scope. Restart Pi and confirm Pine is absent from the list. Keep agents/, .pine/, ~/.pine/ and ~/.local/state/pine/ (or the configured XDG_STATE_HOME/pine/): these hold saved work, records and settings. Agent conversations live under agents/lib/<name>/sessions/ and are ignored by Git. If the optional shell shortcut was created, remove only the file identified by its "Installed by /pine install-command" marker. Pi and herdr are separate tools; removing Pine does not require removing either.

Sources

Verified against the supplied Pine 0.13.0 source and official documentation on 2026-10-25. The environment journal distinguishes commands actually executed from platform branches checked against documentation.

• Pi installation and providers.
• Pi 1.4 package commands and source identity.
• Pi 1.4 Node requirement.
• herdr installation.
• Pine prerequisites and commands.