Product case study · September 1, 2026

Pi Coding Agent: start with the core, then review every package

Install Pi without lifecycle scripts, distinguish built-in MCP from third-party packages, and check project trust before a sandboxed task.

Reading time
14 min
Checked
Nov 20, 2026
A charcoal tool block in a warm paper enclosure beside a separate muted blue package tile and an ochre inspection lens.
Pi's core, extensions, packages, provider, and sandbox are separate layers with separate trust decisions.
Bottom line

Pi is a minimal, extensible terminal coding harness rather than an all-in-one autonomous platform. Its core gives the model file and shell tools; extensions and packages add behavior as separately trusted software. Project trust is useful for controlling project-local loading, but it is not isolation: use a container, VM, or policy-controlled sandbox for untrusted or unattended work.

Documentation checked November 20, 2026. Pi is a terminal coding harness designed to keep its core small and move customization into TypeScript extensions, skills, prompt templates, themes, and Pi packages. The distinction matters: a third-party extension or package adds code and instructions you choose to trust. Pi also ships built-in extensions, including the MCP support described below.Pi documentationnpm package

This refresh checks current official documentation; it does not report an authenticated agent run, package audit, or measured sandbox result. The 0.84.4 examples and companion lesson remain historical pins from September 1, not a claim about the latest release. Check your installed version and its help before using newer options.

Pi is not a substitute for every adjacent system. It is strongest when you want a compact coding-agent loop that you can extend deliberately. It is not, by itself, a broad cross-channel automation platform, a durable worker runtime, or a sandbox.

Install the supported package, then remove it cleanly

The npm route requires Node.js 22.19 or newer according to the current quickstart. It does not pin transitive dependencies, even when you pin Pi itself. Save the dependency tree or lockfile for a reproducible evaluation.Pi quickstart

The supported npm package and namespace are exact:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

--ignore-scripts disables dependency lifecycle scripts during this install; Pi documents that it does not require install scripts for a normal npm installation. Do not copy older @mariozechner commands: the maintained package is @earendil-works/pi-coding-agent.Pi quick start

Use the matching package-manager command to remove a global npm installation:

npm uninstall -g @earendil-works/pi-coding-agent
command -v pi || true

If you installed through pnpm, Yarn, or Bun, use that manager’s corresponding global removal command instead. Removing the CLI does not automatically audit or delete Pi configuration, sessions, or separately installed packages; inspect ~/.pi/agent before deleting anything you need to retain.Pi quick start

For a reversible evaluation of the historical version used by the companion lesson, avoid the global install altogether:

mkdir -p /tmp/pi-eval/tool
npm install --prefix /tmp/pi-eval/tool --ignore-scripts \
  @earendil-works/pi-coding-agent@0.84.4
/tmp/pi-eval/tool/node_modules/.bin/pi --version

That is an installer inspection, not a security proof. Inspect the unpacked package, its dependency tree, and any package you later add before letting it access a real repository or credential.

What belongs to which layer

LayerWhat it isWhat it does not prove
Pi coreThe coding-agent CLI, default tool loop, interactive UI, print/JSON mode, RPC mode, and SDK.That a model response is safe, correct, or contained.
Core toolsThe default read, write, edit, and bash tools exposed to the selected model.A least-privilege filesystem or process boundary.
Skills and prompt templatesReusable instructions and prompts loaded on demand.That model-followed instructions cannot request risky actions.
ExtensionsTypeScript modules that can add tools, commands, events, and UI.That added code has less access than Pi.
Pi packagesnpm, Git, or local bundles of extensions, skills, prompts, and themes.That a popular package has been reviewed or is safe.
ProviderThe subscription login, API key, or local router that supplies a model.That host files selected as context remain local.
SandboxA container, VM, micro-VM, or policy-controlled boundary around the process or tools.That application-level project trust alone contains the workload.

Pi’s own security guide is explicit: its built-in tools and extensions run with the permissions of the process that starts Pi. Project trust decides whether project-local resources load; it is not a sandbox and does not constrain what a running model can ask the tools to do.Pi security

The core: intentionally small

A default Pi session lets the model read files, write files, edit files, and run shell commands. Authenticate interactively with /login, or configure a supported API key before starting the session. The package documents subscription providers including Anthropic, OpenAI/Codex, and GitHub Copilot, as well as a long list of API-key providers and a llama.cpp route.Pi providers

The core has several ways to operate:

ModeUse it for
Interactive TUIA supervised repository task, model selection, session navigation, and explicit human review.
Print or JSONA one-shot or automation-friendly run that emits text or structured events.
RPCA process integration over stdin/stdout JSONL.
SDKEmbedding Pi’s agent capabilities inside a Node.js application.

Those modes change integration shape, not the trust boundary. A non-interactive invocation can be convenient in CI or a script, but it must receive a provider credential and should run only within the same explicit containment you would use for an interactive agent.Pi documentation

Historical release context: 0.84.4

The August 28, 2026 v0.84.4 release adds terminal capability overrides for hyperlinks, images, and truecolor; ui_prompt_start and ui_prompt_end extension events; an RPC clear_queue operation; and experimental deepseek-v4-flash-vision-exp support. It also fixes important session, tool-result ordering, and compaction behavior, including a resumed JSONL trailing-newline issue and compaction timing around large tool output.Pi v0.84.4 release

Treat that release information as version-specific. Check pi --version before relying on a flag, tool behavior, or fix from this page.

Packages are separate software

Pi packages can bundle extensions, skills, prompt templates, and themes. Pi supports npm, Git, and local-path sources; installing or removing a package normally changes either global ~/.pi/agent/settings.json or project .pi/settings.json. A project package can be installed automatically after the project is trusted.Pi package documentation

That convenience creates a serious boundary: Pi’s package documentation says packages run with full system access, extensions execute arbitrary code, and skills can instruct the model to run executables. Review source before installing a third-party package.Pi package documentation

Use a short review checklist before adding one:

  1. Record the package name, version, publisher, source repository, licence, and date checked.
  2. Read package.json, the Pi manifest, the entry extension, dependencies, and install/update behavior.
  3. Identify filesystem access, child-process launches, network calls, credential stores, MCP servers, and any host-config discovery.
  4. Pin the npm version or Git revision for an evaluation.
  5. Try it only in an isolated disposable workspace, then test its removal and the settings diff.
  6. Do not describe package behavior as Pi core behavior.

Package example: pi-mcp-adapter is third-party

pi-mcp-adapter is a third-party Pi package, not Pi core. In the September 1 snapshot, the Pi catalog listed version 2.31.0, published August 28, 2026, as an extension/skill package with 12 dependencies and four peer dependencies. Its declared manifest loads ./index.ts and ./skills; its stated purpose is a token-efficient MCP adapter.Pi catalog entry

Its repository says it can read standard MCP configuration files and can start MCP servers lazily when a tool is used. That can be useful, but it also expands the trust surface to configuration discovery, server commands, MCP endpoints, OAuth flows, and their credentials. The package’s own documentation says host-specific configuration discovery is off by default and that it does not silently launch commands from discovered host configs; verify that behavior against the pinned source you install, not only this article.pi-mcp-adapter repository

The historical example below loads a package for one invocation without adding it to settings. That does not mean it leaves no files: current Pi docs describe a cache under ~/.pi/agent/tmp/extensions/. Exact npm pins avoid version checks; an unpinned specification can refresh its cached copy. Inspect that cache during cleanup.Pi package documentation

After source review, a version-pinned trial uses:

pi -e npm:pi-mcp-adapter@2.31.0

Run it only after source review and only in a sandbox that has no real MCP credentials or broad host mounts. For a persistent install, use the documented package command, then verify settings and removal:

pi install npm:pi-mcp-adapter@2.31.0
pi list
pi remove npm:pi-mcp-adapter
pi list

The package catalog’s downloads or ranking are popularity signals, not a safety audit. On September 1, 2026, the catalog showed pi-mcp-adapter, pi-web-access, and pi-subagents among high-download entries; that does not transfer any package’s behavior or security properties to Pi core.Pi package catalog

Check built-in MCP before installing an adapter

Current Pi documentation includes built-in MCP support for stdio and streamable HTTP servers. An adapter is therefore an optional third-party choice, not a prerequisite for every MCP connection. User configuration lives at ~/.pi/agent/mcp.json; project configuration lives at .pi/mcp.json and is gated by project trust.Pi MCP documentation

Before choosing either route, inspect the server executable, arguments, working directory, endpoint and credential references. Use a disposable environment with no existing server configuration for the first experiment. Do not run a server-listing command against unknown configuration merely to inspect it: the documented setup uses that command to check connections.

If the built-in route supplies the needed tool, avoid adding an adapter solely because an older tutorial used one. If an adapter supplies a required feature, record that feature and test it separately. A successful connection proves reachability, not that a server’s tools are safe or its answers are correct.

Project trust is an input guard, not containment

Pi looks for project-local settings and resources such as .pi/extensions, .pi/skills, and project .agents/skills. A first interactive session normally asks whether to trust those resources; non-interactive modes use the configured default unless a one-run approval flag overrides it. Context files such as AGENTS.md and CLAUDE.md are still loaded unless context loading is disabled.Pi security

The current security guide documents an exception: Pi reads project sessionDir while selecting a session, before resolving trust. Declining trust cannot undo that lookup. Context files also include AGENTS.override.md, which loads regardless of trust unless context loading is disabled.Pi security

Trust therefore gates most project resources rather than every startup read. It does not turn untrusted repository text, prompt injection, generated output, shell commands, or model output into safe input. Start unknown repositories with no project trust, inspect their context files manually, and use operating-system isolation for any task that will execute tools.

Make a reduced-resource launch explicit

Inside an already established disposable sandbox, save pi --version and inspect pi --help. If your installed version documents every option below, this is a starting configuration for a supervised core-tool trial:

pi --no-approve --no-extensions --no-mcp \
  --no-skills --no-prompt-templates --no-context-files \
  --tools read,write,edit,bash

These flags decline project trust, suppress automatically loaded resources and select the four tools. Do not append explicit extension or skill paths: those can still load despite the corresponding discovery-disable flags. --no-mcp disables built-in MCP, not an extension implementing its own MCP support. A tool list alone is not an MCP off switch.Pi CLI reference

Before entering a task, inspect startup output for unexpected resources. If a flag is unsupported or an unwanted integration appears, stop and reconcile the installed version and configuration. Afterward, independently check the requested test and changed-file list. This launch is documentation-backed, not an executed result; bash still has the process’s filesystem and network access.

Pick a real isolation pattern

Pi documents these isolation patterns:

PatternBoundaryImportant caveat
Gondolin extensionRoutes built-in tools and ! commands into a local micro-VM while Pi itself stays on the host.Other custom extension tools still run where Pi runs unless they delegate too.
Plain DockerRuns the entire Pi process in a container.A writable bind mount still changes host files; API keys enter the container.
Docker SandboxesRuns the entire Pi process in a managed sandbox with a credential proxy.Configure credentials on the host; Pi warns against /login inside this sandbox because it stores a real credential there.
OpenShellRuns the entire Pi process in a policy-controlled sandbox.It requires an active gateway and policy setup.

For a first task, copy a disposable repository into a container or remote sandbox rather than bind-mounting a valuable host checkout. Mount only what the task needs, keep host ~/.pi/agent out of the sandbox, pass no production credentials, and constrain egress to the model endpoint and explicitly required registries. Pi’s security documentation also warns that a read/write bind mount gives the sandbox direct ability to modify host files.Pi containerizationPi security

Pi, Hermes, and Herdr: adjacent layers, not replacements

Product layerBest descriptionDo not infer
PiA minimal, extensible coding harness for a selected model and repository task.That it supplies a durable multi-agent operating platform or a sandbox.
HermesA broader autonomous-agent platform with profiles, skills, messaging, background jobs, and multiple interaction surfaces.That a Hermes profile or permission setting itself provides OS-level containment.
HerdrA persistent terminal runtime and orchestration layer for longer-lived agent work.That it is the same sort of minimal coding harness as Pi.

A team can use Pi as the narrowly scoped coding harness inside a separately chosen runtime or automation system. The right comparison is therefore layer-by-layer: task loop, extension surface, persistence/orchestration, provider access, and explicit isolation.

A finish line worth recording

Before calling a Pi evaluation complete, retain:

  • Pi and package versions, source URLs, and the date checked;
  • the sandbox engine and its policy or Docker arguments;
  • provider/model, authentication route, token or cash cost, and setup time;
  • the exact prompt and human corrections;
  • the requested test result, git diff --check, changed-path list, and final diff;
  • proof that an out-of-scope filesystem probe was denied by the sandbox;
  • package install/removal settings before and after; and
  • a clean shutdown or restart result if the workflow claims detach/restart behavior.

The companion lesson gives a disposable-repository procedure and insists on recording a failed preflight honestly. Do not replace missing sandbox, provider, or package-inspection evidence with a reassuring completion message.

Sources

Current documentation checked November 20, 2026; the release and catalog snapshots explicitly marked September 1 remain historical context. No package safety certification is implied.

Put this to work

Draw the trust boundary around every installed package and every mounted directory, not just around the Pi executable.

Try

Follow the companion sandboxed first-task lesson in a disposable copy after checking that its Docker or OpenShell prerequisite is available.

Prove it worked

Keep the version, package source and version, model/provider, test output, diff, sandbox-denial result, and uninstall result together.

Where it can pay

A reproducible, bounded agent workflow can become a safer code-review or implementation service.

Keep in view

  • Install the current `@earendil-works/pi-coding-agent` package with npm lifecycle scripts disabled; remove the same package with npm when finished.
  • Core Pi has four default model tools: read, write, edit, and bash. Skills, extensions, prompts, themes, and packages are separate layers.
  • Pi project trust controls loading of project resources; it does not reduce the permissions of Pi, its shell commands, or installed extensions.
  • Current Pi docs include built-in MCP; review server configuration before adding a third-party adapter.
Learn the workflow: the sandboxed Pi first-task tutorial