# 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](https://pine-pi.vercel.app/docs/api.md) 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](https://pine-pi.vercel.app/llms.txt) to discover supported operations.
For feature guides, start with the [Pine documentation](https://pine-pi.vercel.app/docs/).

## 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:

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

```sh
pi --version
```

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

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

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

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

```sh
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](https://github.com/herdrdev/herdr/releases/tag/v0.9.5)
table. Linux/macOS assets are bare executables; do not unzip them.

| Machine | PINE_HERDR_ASSET | PINE_HERDR_SHA256 |
| --- | --- | --- |
| Linux x86_64 | herdr-linux-x86_64 | 14d9e8bc8b4a9e0118d77c32266f76d461f09b40342eb23752960bd89f59929d |
| Linux aarch64 | herdr-linux-aarch64 | 17d7536f2da50859523680ef279dffcac8e4a235f4e46fe8da6c2ec44141897c |
| macOS arm64 (Apple silicon) | herdr-macos-aarch64 | fb77c2232a05a8035421382c894392f4174e4e38a18e48af3dd0290157c3a7e2 |
| macOS x86_64 (Intel) | herdr-macos-x86_64 | 5fb0a908ec7f6745e3e245738b06bfad56c46391c391ab3c0955fbead01f1369 |

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.

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

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

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

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

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

```text
/reload
```

Then check that the Pine guide appears:

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

```text
/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**:

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

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

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

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

```text
/pine close all
```

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

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

For the local source above, use this instead:

```sh
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](https://pi.dev/).
- [Pi 1.4 package commands and source identity](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/packages.md).
- [Pi 1.4 Node requirement](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/package.json).
- [herdr installation](https://herdr.dev/docs/install/).
- [Pine prerequisites and commands](https://github.com/johnlindquist/pine/blob/v0.13.0/README.md).