@nathanpt/pi-onboard

Pi extension for onboarding into a repository: generates AGENTS.md and a visual HTML overview.

Packages

Package details

extension

Install @nathanpt/pi-onboard from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:@nathanpt/pi-onboard
Package
@nathanpt/pi-onboard
Version
0.4.0
Published
Jun 21, 2026
Downloads
not available
Author
nathanpt
License
MIT
Types
extension
Size
28.6 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions/index.ts"
  ],
  "image": "https://raw.githubusercontent.com/nathanpt/pi-onboard/main/docs/preview.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-onboard

Status: design stage. The /onboard extension is not yet implemented. This repository currently holds the design and research docs (docs/). The install commands below describe the intended release. Star/watch if you want the first cut.

A Pi extension for onboarding into an unfamiliar repository. Run /onboard and pi-onboard inspects the repo, infers what it is and how it's built, and writes durable orientation artifacts you (and future coding-agent sessions) can actually use.

What it produces

Two artifacts in the repo root:

  • AGENTS.md — a lean, confidence-aware context file for future harness sessions. Hand-edits are never clobbered: pi-onboard updates only its own marker-bounded sections, or writes a AGENTS.pi-onboard.draft.md if the file was authored by hand.
  • pi-onboard-overview.html — a single-file, dark, interactive visual overview (repo map, commands with confidence badges, conventions, where to start). It is also served over HTTP so you can open it from a browser on another machine.

Install

# from npm (once released)
pi install npm:@nathanpt/pi-onboard

# from git
pi install git:github.com/nathanpt/pi-onboard

# try without installing
pi -e npm:@nathanpt/pi-onboard

Usage

/onboard                    # full analysis, safe write
/onboard --force            # overwrite existing files
/onboard --text-only        # skip the HTML overview (and the server)
/onboard --no-serve         # write the HTML file but don't start a server
/onboard --port 4321        # pin a server port (default: OS-assigned)
/onboard --host 127.0.0.1   # bind address (default: 0.0.0.0)
/onboard --idle-timeout 60  # server idle shutdown, minutes (default: 30)
/onboard --help             # show usage

How it works

  • AI-driven. The command does a quick static discovery pass to gather repo signals (dependencies, scripts, directories, README excerpt), then fills your editor with a structured prompt. Press Enter and the agent reads your source files, understands the project, and writes genuinely useful artifacts.
  • Safe by default. Existing files are never silently overwritten — a .draft variant is created instead.
  • Node/TypeScript and Python first. Other ecosystems are best-effort.

Security note

The overview server binds to 0.0.0.0 by default so it's reachable from remote machines (SSH sessions, dev boxes, CI runners behind a tunnel). It serves only the generated overview (repo-derived paths/commands/conventions — not arbitrary file access), auto-stops after 30 min idle, and lives behind an unguessable URL token. Use --host 127.0.0.1 for local-only access. pi-onboard makes no outbound network calls; the HTTP server is the only network surface.

Docs

License

MIT © Nathan Peet. See LICENSE.