harness-tools/README.md

harness-tools

Personal Pi extensions, skills, global agent instructions, sandbox profiles, and supporting services.

What this repository installs

config/pi-links.json is the source of truth for the normal installation. The link manager exposes:

• global agent instructions for Pi, Codex, and Claude;
• 34 shared skills under ~/.agents/skills/;
• the manage-pi-links and nono-profiles project-only skills under .pi/skills/;
• no global Pi extension symlinks. Active extensions are installed separately as pinned Gitea npm packages.

The repository contains copy-all, dictate (Linux host-service dictation), effort-controls, file-search, interactive-subagents, lm-studio, native-hooks, prompt-snippets, subagents, todo-herdr, update, and the private workflow extension. The link manifest does not install any of them globally. The pptx, stop-slop, subagents, and xlsx skills are also intentionally excluded. Archived resources under __archived/ are never installed. Update config/pi-links.json deliberately if that policy changes.

Fresh-machine setup

The commands below reproduce the normal setup. They assume Linux, a systemd user session, and the current canonical checkout path. Pi and the shared skills work on other platforms, but the nono launcher and Dictate sections are Linux-specific.

1. Install the base tools

Required:

• Git with access to git.jb.codes;
• Node.js 22.19 or newer;
• Bun 1.3.14 or newer;
• Pi Coding Agent;
• a configured model provider.

Install Pi using its official npm package:

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

A Bun global install also works, but record its executable path later when configuring pi-sbx.

Start Pi once and authenticate with a subscription or API-key provider:

pi

Run /login inside Pi. Pi stores its user state under ${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}. When Pi runs through nono, prefer nono credential routes so real API keys do not enter the sandbox; see Sandboxed Pi credentials.

2. Clone the repository

Several current profiles and instruction imports contain /srv/data/code/harness-tools, so using that path requires no repository edits:

if [ ! -e /srv/data/code ]; then
  sudo install -d -o "$USER" -g "$(id -gn)" /srv/data/code
fi
test -d /srv/data/code && test -w /srv/data/code || {
  echo '/srv/data/code already exists but is not a writable directory' >&2
  exit 1
}

git clone ssh://git@git.jb.codes:7722/jb/harness-tools.git \
  /srv/data/code/harness-tools
cd /srv/data/code/harness-tools

The setup creates /srv/data/code only when absent. If it already exists, keep its current ownership and obtain access through the machine's normal administration policy.

If the checkout lives elsewhere, replace the machine-specific paths before syncing:

• docs/global.CLAUDE.md;
• profiles/nono/pi-local.json;
• profiles/nono/pi-orca-local.json;
• profiles/nono/pi-work.json;
• the copied ~/.config/pi-sbx/config.json described below.

Dictate currently targets /run/user/1000/pi-dictate.sock in both the extension and profile. It therefore expects UID 1000. Change and review the socket path before installation if id -u reports another UID.

3. Install repository dependencies

The monorepo's typechecking, tests, packaging, and extension development require its Bun dependencies even though extensions ship as TypeScript source:

cd /srv/data/code/harness-tools
bun install --frozen-lockfile
bun run typecheck

Use bun install --frozen-lockfile after pulling a lockfile change and plain bun install only when intentionally updating bun.lock. Node.js and Bun must satisfy the versions in package.json.

4. Install instructions and skills

Preview the exact changes first, then apply them:

cd /srv/data/code/jb-pi/harness-tools
./scripts/pi-links.mjs sync --dry-run
./scripts/pi-links.mjs sync
./scripts/pi-links.mjs check

A successful check currently reports 39 links and zero local package entries. The manager:

• preserves unrelated global resources;
• refuses to overwrite regular files, directories, or links owned outside this repository;
• uses absolute links for global resources and relative links for project-only skills.

Resolve any reported collision manually instead of deleting it blindly. Run /reload in an active Pi session, or restart Pi, after the sync.

The repository root is a private Bun workspace and is not installable as a Pi package. The curated config/pi-links.json policy manages instructions and skills but deliberately exposes no extension symlinks. Install published @jbcode/pi-* packages for normal use; use explicit local paths only for temporary development. See Bun workspace packages and Gitea npm publishing.

5. Verify Pi

Install the desired pinned packages from Optional Pi packages from Gitea, then start Pi:

pi

Inside Pi:

1. Run /reload.
2. Confirm /effort and /snippets are available.
3. Ask Pi to list its available skills and confirm a shared skill such as tdd appears.
4. From this repository, confirm the project-only manage-pi-links and nono-profiles skills appear.

Optional Pi packages from Gitea

The currently published and deployed extension set is:

• @jbcode/pi-dictate@0.2.0;
• @jbcode/pi-effort-controls@0.1.0;
• @jbcode/pi-prompt-snippets@0.1.0;
• @jbcode/pi-interactive-subagents@3.7.3;
• @jbcode/pi-todo-herdr@0.2.5.

Configure the scoped Gitea npm registry and install only the packages you want. Keep the token in the user environment or user-level npm configuration; never commit it:

@jbcode:registry=https://git.jb.codes/api/packages/jb/npm/
//git.jb.codes/api/packages/jb/npm/:_authToken=${GITEA_NPM_TOKEN}

pi install npm:@jbcode/pi-dictate@0.2.0
pi install npm:@jbcode/pi-effort-controls@0.1.0
pi install npm:@jbcode/pi-prompt-snippets@0.1.0
pi install npm:@jbcode/pi-interactive-subagents@3.7.3
pi install npm:@jbcode/pi-todo-herdr@0.2.5
pi list

Restart Pi or run /reload afterward. These package entries remain independent of config/pi-links.json, so ./scripts/pi-links.mjs check still reports zero local package entries.

Do not globally enable harness-tools/extensions/subagents at the same time as pi-interactive-subagents. They provide overlapping subagent tools. The curated harness-tools manifest leaves its in-repository implementation disabled for this reason.

Configure interactive subagents

@jbcode/pi-interactive-subagents creates asynchronous child Pi sessions in Herdr tabs or tmux panes. It requires one terminal backend:

• Herdr: install its Pi integration, then launch Pi inside a Herdr-managed pane;
• tmux: launch Pi inside tmux when Herdr is unavailable.

For Herdr:

herdr integration install pi
herdr integration status
herdr

Start Pi in a Herdr pane. The extension detects HERDR_ENV=1 and opens each subagent in an unfocused tab. The pi-local nono profile already declares the reviewed Herdr socket used on the original machine; update that machine-specific path if necessary.

For tmux:

tmux new -A -s pi 'pi'

The package bundles scout, researcher, and worker agent definitions. Their configured provider, model, thinking level, and tool allowlist live in the package's agents/ directory. Authenticate the configured provider and confirm the named model is available. To override a bundled definition without editing Pi's managed Git clone, create a same-named file in ${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/agents/ or a trusted project's .pi/agents/; project definitions take precedence over global definitions, which take precedence over package definitions.

Inside Pi, verify and try the extension:

1. Run /reload.
2. Ask Pi to call subagents_list.
3. Confirm scout, researcher, and worker are listed.
4. Run /subagent scout Summarize this repository from a disposable test checkout.
5. Confirm a Herdr tab or tmux pane opens and the completed result returns to the parent session.

The status widget is enabled by the package's example configuration when no local config.json exists. Copy and edit config.json.example beside the installed package only when a status override is needed. Treat Pi's managed package installation as disposable because package updates may reset it; prefer global or project agent overrides for durable customization.

Configure Native Hooks

@jbcode/pi-native-hooks coordinates trusted personal diagnostic and verification policies after workspace mutations. Review its trust model and initialization workflow before use. Preview with /hooks-init --dry-run; do not run /hooks-init --apply until every destination and executable policy has been reviewed.

Configure Pi Todo Herdr

@jbcode/pi-todo-herdr provides the set_tasks, patch_tasks, rm_task, list_task, and get_task tools plus a session-local Pi task widget. Herdr is optional for the tools and widget.

Inside Pi after /reload:

1. Confirm the five task tools are available.
2. Run /todo to toggle the widget.
3. Ask Pi to create a small three-step test plan, update one task, and list the tree.

For Herdr sidebar task metadata, back up and edit the existing configuration:

cp -a ~/.config/herdr/config.toml \
  ~/.config/herdr/config.toml.before-pi-todo-herdr
"${EDITOR:-vi}" ~/.config/herdr/config.toml

If [ui.sidebar.agents] already exists, edit its existing rows value and add "$task_progress", "$task", and "$task_count" where desired. Do not add a duplicate TOML table header. If the table does not exist, append the complete block:

[ui.sidebar.agents]
rows = [["state_icon", "workspace", "tab"], ["$ask", "$ask_count"], ["$task_progress", "$task", "$task_count"]]

Apply and verify the change:

herdr server reload-config
herdr status client

Update or remove the Gitea packages

These installations are version-pinned. After publishing a new version, install that exact spec to replace the prior pin. Remove packages by npm identity:

pi remove npm:@jbcode/pi-dictate
pi remove npm:@jbcode/pi-effort-controls
pi remove npm:@jbcode/pi-prompt-snippets
pi remove npm:@jbcode/pi-interactive-subagents
pi remove npm:@jbcode/pi-todo-herdr

Run /reload after a version change or removal.

Imported source provenance

The three packages were imported as snapshots of their source repositories' main branches. config/imported-packages.json records each source and exact commit. Check for upstream movement without changing this checkout:

bun run imports:check

Stage fresh snapshots outside the repository for review and reconciliation:

bun scripts/import-package-snapshots.mjs stage all --output /tmp/harness-tools-imports

The stage command deliberately does not overwrite monorepo files. Review upstream changes, preserve the scoped package manifests and catalog dependencies, run the full validation suite, and then update the recorded commit.

Companion tools used by installed skills

The link sync installs skill instructions, not every external program those skills may call. Install the companion tools you intend to use.

OpenSrc for dependency research

code-research and package-source require the opensrc CLI and intentionally use /srv/data/opensrc as the single source cache:

npm install -g --prefix "$HOME/.local" opensrc
if [ ! -e /srv/data/opensrc ]; then
  sudo install -d -o "$USER" -g "$(id -gn)" /srv/data/opensrc
fi
test -d /srv/data/opensrc && test -w /srv/data/opensrc || {
  echo '/srv/data/opensrc already exists but is not a writable directory' >&2
  exit 1
}

if [ ! -e "$HOME/.opensrc" ] && [ ! -L "$HOME/.opensrc" ]; then
  ln -s /srv/data/opensrc "$HOME/.opensrc"
fi

command -v opensrc
readlink -f "$HOME/.opensrc"

The setup preserves existing directory ownership and any existing ~/.opensrc. If that path already exists, inspect it instead of replacing it. Completion requires it to resolve to /srv/data/opensrc.

If ~/.opensrc already exists, inspect it instead of replacing it. Completion requires it to resolve to /srv/data/opensrc.

Browser Harness

The browser-harness skill requires uv, Chrome or Chromium, and the Browser Harness CLI:

uv tool install --python 3.12 --upgrade --force browser-harness
browser-harness --doctor
browser-harness <<'PY'
print(page_info())
PY

For a Browser Use cloud session, authenticate separately with browser-harness auth login. Local browser control does not require a cloud key.

Artifact presentation

The artifact-presenter skill uses Herdr and mcat. Install both and verify:

command -v herdr
command -v mcat
herdr --version
mcat --version

On Arch-based systems, mcat is available as the mcat-bin AUR package. Follow Herdr's installation guide for its CLI. The skill falls back to reporting the artifact path when either program is unavailable.

PDF work

The pdf skill calls tools as needed rather than maintaining a repository environment. For its common workflows, install the relevant subset of:

• Python packages: pypdf, pdfplumber, reportlab, pymupdf, pytesseract, and pdf2image;
• system tools: Poppler (pdftotext, pdfimages, and pdftoppm), qpdf, and Tesseract OCR.

The intentionally excluded pptx and xlsx skills have additional office and rendering dependencies and are not part of the normal setup.

Optional Linux sandbox setup

The repository-managed nono profiles and pi-sbx launcher are optional, but they reproduce the normal restricted Pi runtime.

Install nono and its Pi package

Install the nono CLI using its upstream instructions, then pull the parent Pi profile:

nono pull nolabs-ai/pi
nono profile show nolabs-ai/pi

Link the repository profiles

cd /srv/data/code/harness-tools
mkdir -p ~/.config/nono/profiles

for profile in pi-local pi-orca-local pi-harness-tools pi-work; do
  source="$PWD/profiles/nono/$profile.json"
  destination="$HOME/.config/nono/profiles/$profile.json"
  if [ -L "$destination" ] && \
     [ "$(readlink -f "$destination")" = "$(readlink -f "$source")" ]; then
    continue
  fi
  if [ -e "$destination" ] || [ -L "$destination" ]; then
    echo "Refusing to replace existing profile: $destination" >&2
    exit 1
  fi
  ln -s "$source" "$destination"
done

for profile in pi-local pi-orca-local pi-harness-tools pi-work; do
  nono profile validate "$profile"
done

The loop is rerunnable for links already targeting this checkout and refuses every other collision.

These profiles inherit from one another, so install and validate all four even if only pi-local is used initially. Review their filesystem paths, Orca integration paths, socket grants, network allowlist, and work-specific Git path on every new machine.

Install the routed launcher

pi-sbx is a Fish script. Install Fish, then link the launch commands and systemd slice:

cd /srv/data/code/harness-tools
mkdir -p ~/.local/bin ~/.config/pi-sbx ~/.config/systemd/user

safe_link() {
  source="$1"
  destination="$2"
  if [ -L "$destination" ] && \
     [ "$(readlink -f "$destination")" = "$(readlink -f "$source")" ]; then
    return 0
  fi
  if [ -e "$destination" ] || [ -L "$destination" ]; then
    echo "Refusing to replace existing path: $destination" >&2
    return 1
  fi
  ln -s "$source" "$destination"
}

safe_link "$PWD/scripts/pi-sbx.fish" "$HOME/.local/bin/pi-sbx"
safe_link "$PWD/scripts/pi-sbx-profile.py" "$HOME/.local/bin/pi-sbx-profile"
safe_link "$PWD/scripts/pi-orca.fish" "$HOME/.local/bin/pi-orca"
safe_link "$PWD/scripts/orca-nono-profile.py" "$HOME/.local/bin/orca-nono-profile"
safe_link "$PWD/systemd/user/pi-agents.slice" \
  "$HOME/.config/systemd/user/pi-agents.slice"

if [ ! -e "$HOME/.config/pi-sbx/config.json" ]; then
  cp "$PWD/config/pi-sbx.example.json" "$HOME/.config/pi-sbx/config.json"
  chmod 600 "$HOME/.config/pi-sbx/config.json"
else
  echo 'Keeping existing ~/.config/pi-sbx/config.json'
fi
systemctl --user daemon-reload

The setup preserves an existing launcher, systemd unit, or routing configuration unless it already links to this checkout. Resolve reported collisions manually after inspecting both paths.

Edit ~/.config/pi-sbx/config.json before launching. Set:

• nodeExecutable to readlink -f "$(command -v node)";
• piExecutable to the real Pi executable path;
• piAgentDirectory to the matching Pi state directory;
• directory routes to paths that exist on this machine;
• profile-specific runtimes only when a different Node ABI or Pi state directory is intentional.

The checked-in example contains paths from the original machine and is a template, not a portable final configuration. Separate Pi agent directories are required when profiles use incompatible Node ABIs with native dependencies.

Verify and launch:

pi-sbx-profile list
pi-sbx-profile show
pi-sbx-profile set pi-local /path/to/a/project
pi-sbx-profile resolve /path/to/a/project
pi-sbx

See docs/nono.md for routing behavior, multi-repository grants, Internet tiers, profile editing, and troubleshooting denials.

Sandboxed Pi credentials

The base nolabs-ai/pi package supports mediated credential routes. Store secrets in the OS keychain or another nono-supported secret source, then enable only the required route names in a reviewed child profile. For example, supported built-in route names include openai, anthropic, gemini, github, and gitlab.

Do not place real provider keys in files readable by sandboxed Pi if the goal is credential mediation. Consult the installed package guide after nono pull:

~/.config/nono/packages/nolabs-ai/pi/README.md

Optional Dictate service

Dictate is a Linux-only host service. Every backend requires:

• PipeWire with pw-record;
• systemd user services;
• uv;
• access to the exact /run/user/1000/pi-dictate.sock, unless the socket path is changed for another UID.

The default backend is local NeMo/Parakeet. Local installation additionally requires an NVIDIA GPU, a working CUDA runtime, network access for initial provisioning, and several gigabytes for the locked environment and pinned model. Meta and OpenAI are explicit cloud opt-ins. Cloud-only installation does not install NeMo, CUDA, or model weights, but it requires a dedicated host credential and outbound DNS/TLS access from the service.

Install one backend from the repository root:

cd /srv/data/code/harness-tools
./services/dictate/install.sh install --backend local
# or:
./services/dictate/install.sh install --backend meta --api-key-file /path/to/meta-key
./services/dictate/install.sh install --backend openai --api-key-file /path/to/openai-key

--api-key-file copies a regular source file into the host-owned mode-0600 credential directory. Never pass a literal key. Configure an installed backend or validate it with:

./services/dictate/install.sh configure --backend local
./services/dictate/install.sh check
systemctl --user status pi-dictate.socket pi-dictate.service

Local mode remains offline after provisioning and uses the checksum-pinned Parakeet archive. Cloud mode streams bounded PCM to the selected provider only after its session is authenticated and ready. Backend changes are privileged host operations, require validation and a service restart, and fail closed if systemd network hardening does not match the selection. The service does not write audio files or expose provider credentials to Pi. Cloud provider retention, terms, and billing policies apply to audio and configured context sent with a cloud session.

Restart a sandboxed Pi after profile or socket changes. In Pi, press Alt+M to start or stop dictation, Alt+N or /dictate-cancel to cancel, and /dictate-status to display bounded backend/model diagnostics. See extensions/dictate/README.md for configuration, provider links, privacy, dictionary, model, and troubleshooting details.

Maintenance

After pulling repository changes:

cd /srv/data/code/jb-pi/harness-tools
git pull --rebase
bun install --frozen-lockfile
./scripts/pi-links.mjs sync --dry-run
./scripts/pi-links.mjs sync
./scripts/pi-links.mjs check
bun run typecheck

Run /reload after skill, extension, instruction, or separately installed Gitea package changes. Re-run ./services/dictate/install.sh when Dictate's host service or protocol changes.

Before removing repository-managed exposure, preview exactly what will be deleted:

./scripts/pi-links.mjs prune --dry-run

Only run ./scripts/pi-links.mjs prune after reviewing every removal. The manager prunes repository-owned exposure and leaves unrelated global resources alone.

Development and checks

Extensions are TypeScript modules loaded directly by Pi; no build step is required.

bun install --frozen-lockfile
bun run typecheck
bun run test

For a one-off extension development run:

pi -e ./extensions/effort-controls
pi -e ./extensions/update

Repository layout

config/        Installation and launcher manifests
docs/          Usage guides, plans, and ADRs
extensions/    Bun workspace packages for Pi extensions and shared runtime code
profiles/nono/ Repository-managed nono profiles
scripts/       Link manager and sandbox launch helpers
services/      Host-side services used by extensions
skills/        Pi skills, one SKILL.md per skill
systemd/user/  Repository-managed systemd user units

License

MIT