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

• docs/DESIGN.md — full design.
• docs/RESEARCH_FINDINGS.md — survey of similar tools and the patterns adopted.

License

MIT © Nathan Peet. See LICENSE.