Contributing

July 26, 2026 ยท View on GitHub

Scope

README.md is for users.

Keep development details, testing notes, internal tool guidance, and docs build details in this file.

Development

Requirements:

  • Node.js 22.19.0 or newer
  • pnpm 10.26.1

Install dependencies:

pnpm install

Run checks:

pnpm typecheck
pnpm lint
pnpm test
pnpm test:e2e

Repository layout

  • src/ - Pi-agnostic process management, types, protocol, and utilities
  • extensions/processes/ - core extension, process tool (start, list, output, update, write, stop, clear), settings, lifecycle hooks, notifications, protocol handlers, /ps, /ps:kill, /ps:clear, and /ps:settings
  • extensions/processes-logs/ - /ps:logs command and log overlay
  • extensions/processes-dock/ - /ps:dock, /ps:pin, the dock widget, and the status widget
  • extensions/shared/ - shared UI helpers (statusDot, processStatusTone, LineComponent, etc.) used across all three extensions
  • skills/ - shipped package skills
  • .agents/skills/ - local repo-only skills for development workflows

Package metadata

The package targets Pi 0.80.3.

Pi bundles core packages for extensions. Keep direct imports of these packages in peerDependencies with "*" ranges and exact local versions in devDependencies:

  • @earendil-works/pi-ai
  • @earendil-works/pi-coding-agent
  • @earendil-works/pi-tui
  • typebox

Keep normal third-party runtime dependencies in dependencies.

Internal behavior

This extension is mainly for agent-managed background processes.

Typical flow:

  1. Pi starts a long-running command in the background.
  2. Pi continues other work.
  3. The user watches, pins, or kills the process from the UI.
  4. Pi inspects output or logs when needed.

Use the process tool for long-running commands such as dev servers, test watchers, build watchers, and log tails.

Avoid shell background patterns when the process tool fits.

Background command blocking is optional. It is controlled by interception.blockBackgroundCommands.

Testing

Useful local checks:

pnpm lint
pnpm typecheck

Useful manual process scripts live under tests/e2e/scripts/:

./tests/e2e/scripts/continuous-output.sh   # long-running stdout
./tests/e2e/scripts/error-log.sh            # interleaved info/error on stdout+stderr
./tests/e2e/scripts/exited-task.sh          # finite, exits 0
./tests/e2e/scripts/crash-on-file.sh <name>  # waits for a marker file then crashes

See .agents/skills/pi-processes-testing/SKILL.md for the full manual QA workflow and the complete fixture script reference.

Docs conventions

README

Keep README.md focused on user outcomes:

  • what the extension does
  • how users interact with it
  • slash commands and UI behavior
  • troubleshooting

Avoid putting these in README.md:

  • dev commands
  • test commands
  • internal architecture details
  • detailed tool-call schemas
  • release workflow notes

Docs page build

The docs page is generated from README.md by an external build, not in this repo. Keep README.md self-contained with only standard markdown.

Future design notes

Unimplemented design notes live in docs/:

  • docs/future-cleanup-hooks.md - planned cleanup support for process start / process stop
  • docs/future-persistent-manager.md - planned cross-session process persistence

These describe intended future behavior, not current behavior. Active implementation work goes under .agents/plans/.