Pylon

Pylon is a web-first coding agent workspace built on Pi. It combines planning, repository research, delegated implementation, verification, safety controls, checkpoints, and a low-noise interface in one bundle.

Pylon is optimized for cost efficiency and output quality rather than speed. It routes focused work to cost-effective models and reserves stronger models for decisions that benefit from them, while verification and specialist reviews help protect quality. This workflow can take longer than using a single model directly.

What Pylon Does

• Deterministic compaction: Continuity intercepts manual and automatic /compact and rebuilds context from structured session state (goal, plan, todos, constraints, verification, file activity) instead of asking a model to summarize. An optional Compaction Reviewer can refine the result, and any failure falls back to the deterministic one.
• Specialized subagents: Advisor (tool-free reasoning for architecture and failure recovery), Scout (bounded repo and public-web reconnaissance), Grunt (delegated implementation in an isolated Git worktree), and Spawn (resumable private threads and child sessions). Each has its own model, so cheap models do the volume and strong models do the decisions.
• File indexing: Discover keeps a machine-local SQLite index of Git-tracked source files, refreshed on session start and reconciled per turn, backing symbol_search and code_search so lookups don't cost a full-repo grep. Repositories shared by several workspaces are indexed once.
• Bounded context: Discover keeps optional tool schemas deferred until search_tools activates them, and every package caps its own output.
• Checkpoints and safety: Timeline takes Git-backed filesystem checkpoints tied to each prompt so you can list, restore, or fork them; Guard intercepts destructive shell and file operations and requires confirmation.
• Verification built in: Verify detects and runs your existing project checks under a time and output budget, and task completion is gated on the result.
• Planning and task lists: Explicit plan mode with structured clarifications, a visible task list, and optional /plan review.
• Tool-aware memory: Durable workspace notes that activate on typed lifecycle and tool events rather than fuzzy prompt similarity. A note attached to a path or tool surfaces when you actually touch it, once per session.

Web App Setup (Recommended)

Requires Node.js 22.19.0 or newer.

npm install --global @fadhilp/pylon
cd /path/to/your/project
pylon

Open http://127.0.0.1:3141 (loopback only) and use Settings to configure providers, package models, and package options. Recommended for OpenAI subscriptions: main GPT 5.6 Sol Medium, Advisor Sol High, Scout Luna Medium, Grunt Terra.

See the complete Pylon Web guide for workspaces, sessions, surfaces, settings, safety, storage, and troubleshooting.

• PYLON_CWD sets the project directory, PYLON_PORT the port (3141), PYLON_NO_UPDATE_CHECK=1 disables the startup update check.
• Sessions, settings, and package state live in ~/.pylon/agent (PI_CODING_AGENT_DIR overrides). Existing ~/.pi/agent data is copied on first run; pylon migrate retries.
• Run pylon changelog for the installed release, pylon changelog <version> for an older release, or pylon changelog --list to list available versions.
• Manage Pi-native extensions in Settings → Extensions. Extensions run arbitrary code with the server's permissions — review sources before enabling.
• Run pylon install <source> to install a Pi extension/package from npm, Git, or a local file/directory into Pylon. For example: pylon install /absolute/path/extension.ts. Pi's install options are forwarded unchanged; use --local --approve for project scope after reviewing the project, and pylon install --help for usage. Reload extensions in Settings afterward.
• Pylon Web agents can use the deferred pylon_settings tool to inspect package settings and apply revision-checked updates after confirmation. The tool does not expose hooks, project policy, trust, extensions, Guard controls, credentials, or raw configuration files.
• Agents can activate the deferred pylon_docs tool to search, list, and read the shipped Web and package documentation on demand; documentation is not injected into every prompt.

Terminal Setup (Alternative)

Requires an existing Pi 1.0.4 install (the web app bundles its own).

pi install npm:@fadhilp/pylon   # or an absolute path to a local checkout

Reload Pi with /reload, then pick models for the child agents — they stay unavailable until configured:

/advisor select
/grunt select
/scout select

Use each command without arguments to show status; set provider/model[:thinking] configures non-interactively, reset uses the current main model, and disable turns the package off. Run /pylon doctor to check models, credentials, dependencies, and package health.

Bundled Packages

Each package works standalone. With Pylon installed, the Pi-facing packages coordinate through bounded, versioned event-bus metadata — Verify results gate Continuity completion and mark Timeline checkpoints, Guard requests a checkpoint before destructive confirmation, Heartbeat publishes job lifecycle, and Scout receives bounded verification context. Raw verification and Heartbeat logs never cross package events. See each package README for details.

Development

Install workspace dependencies and start the local web app from the repository root. The root package-lock.json is the only workspace lockfile; do not generate package-level locks.

npm run install:packages
npm run web

For development without a production build, run npm run dev --workspace @pylon/web.

Run npm run verify for the full checks. Test output hides passing results and success summaries by default, and package verification prints only failed jobs. Failure details and exit codes are preserved. For normal output, pass --verbose after npm’s argument separator: npm test --workspace @pylon/web -- --verbose, npm run test:bundle -- --verbose, or npm run verify -- --verbose.

On Windows, use workspace-relative temporary files when passing paths between Git Bash and native Node/Pylon tools; MSYS paths such as /tmp/... are not native Windows paths. Stop a running Pylon process or use a separate worktree/copy before npm ci, because Windows cannot replace native addons loaded by the active process.