Waypoint

A Pi package for Strong Model presets and a read-only Trellis task tree.

Trellis owns the workflow and native execution. The main agent chooses each trellis_subagent dispatch. Waypoint supplies configuration, routing guidance, and a task projection.

Requirements

• Pi 0.85.1 or a compatible release
• Node.js 22.19 or newer
• A trusted project with native Trellis enabled

Install

After release:

pi install npm:@celia-sh/waypoint@<version>

For a project-local installation:

pi install -l npm:@celia-sh/waypoint@<version>

Install a GitHub tag or commit for unreleased builds:

pi install git:github.com/celia-sh/waypoint@<tag-or-commit>

Run the local source during development:

npm ci
pi --approve -e ./src/index.ts

Routing

Waypoint projects a short policy before each main-agent request. The main agent may choose the configured Strong Model for Trellis research, implementation, or checking and supplies the native model and thinking arguments. Explicit user instructions take precedence.

Mode	Behavior
auto	Guidance when the current and Strong provider/ID differ.
on	Guidance whenever the Strong configuration is usable.
off	Routing guidance disabled; task visibility remains available.

Model choices come from Pi's registry. Thinking choices come from the selected model and the native dispatch capability.

Configuration

The default file is ~/.pi/agent/waypoint.json; PI_CODING_AGENT_DIR is supported.

{
  "defaultMode": "auto",
  "strongModel": {
    "provider": "provider-id",
    "id": "model-id"
  },
  "strongThinking": "high"
}

The initial configuration has no Strong Model. Unsupported saved values remain visible as diagnostics. Session mode changes leave defaultMode unchanged.

Commands

Command	Action
/waypoint	Open the control panel.
/waypoint auto	Use Auto mode for this session.
/waypoint on	Use On mode for this session.
/waypoint off	Use Off mode for this session.
/waypoint model	Select a Strong Model from Pi's registry.
/waypoint thinking	Select a supported thinking level.
/waypoint status	Show configuration and compatibility diagnostics.

Cancelled selectors leave saved settings unchanged.

Task view

The widget reads the current session's native Trellis pointer and bounded task family. Task records are read-only.

• Focused keeps the current lineage, direct children, and nearby sibling roots.
• Collapsed shows the current path and routing summary.
• Full walks the loaded family in native preorder and trims only the tail at the row limit.
• Alt+W cycles Focused -> Collapsed -> Full -> Focused.
• Alt+T opens the loaded family tree.

Inside the tree browser, ↑/↓ and Page Up/Page Down move the selection. Enter and Alt+D open native details, Alt+C toggles related completed records, and Esc closes the browser. The > marker identifies the current session pointer; it is separate from execution state.

Native Trellis cards and Alt+O present dispatch progress, results, models, thinking, usage, tools, and errors.

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run test:integration
npm pack --dry-run

The npm package contains src/, README.md, LICENSE, and package metadata.

License

AGPL-3.0-or-later. See LICENSE.