Primary question: Are you prepared to containerize or sandbox the agent, or will you only run it against repositories you fully trust?
RepoDaily adoption score
RepoDaily rates this as 86/100 (strong) for adoption: evidence, installation path, production risk, differentiation, license clarity, and AI/agent fit are scored from the article sources and adoption notes.
5 source(s) across 3 source category/categories, plus a RepoDaily-specific evidence module when available.
6 workflow step(s), 5 next-action step(s), and 4 command/install signal(s) were detected.
Trending momentum is +603 stars, with maintenance/release/issue signals counted when present.
Risk is marked high, with 6 security note(s) and 4 explicit skip condition(s).
3 opportunity lens item(s), 4 alternative(s), and 3 type-specific section(s) support differentiation.
License source or license wording is present.
5 AI/agent-related signal(s) were detected in the article text and metadata.
Project overview
Pi is a monorepo of four TypeScript packages published under the @earendil-works npm scope by Mario Zechner (known for libGDX). The project describes itself as an 'agent harness'—not a hosted service or a thin wrapper, but a set of local-first building blocks for running AI agents that call tools, manage state, and render terminal output in real time. A separate repository, earendil-works/pi-chat, covers Slack and chat automation.
The four documented packages have clear separation of concerns. pi-ai normalizes LLM calls across OpenAI, Anthropic, and Google behind one API surface. pi-agent-core implements the agent loop with tool calling and state management. pi-tui provides terminal rendering with differential updates—only changed lines are redrawn, which matters when an agent streams tokens at high throughput. pi-coding-agent is the user-facing interactive CLI that orchestrates all three. The build script also references a packages/orchestrator directory that does not appear in the README's package table, suggesting additional infrastructure for multi-agent or pipeline coordination.
What sets Pi apart from most agent tools in 2026 is its security posture. The SECURITY.md is unusually direct about boundaries: there is no sandbox, no permission system, and no filesystem restriction. The coding agent runs with the full permissions of the user that launched it. Prompt injection through AGENTS.md files or code comments is explicitly called out as unprotectable. Rather than pretending these risks don't exist, the project documents three containerization patterns (Gondolin, plain Docker, OpenShell) and puts the responsibility squarely on the operator.
Why it is trending now
- 603 stars in the trending period, ranked 11th, driven by demand for local-first agent infrastructure that doesn't require a hosted backend
- The coding agent is described as 'self-extensible'—the workspace includes example extensions for custom providers (Anthropic, GitLab Duo), sandboxing (Gondolin), and dependency management
- Each package is independently consumable: a developer can install only @earendil-works/pi-ai for multi-provider LLM access without adopting the agent loop, TUI, or CLI
- Supply-chain hardening is rigorous for a project at version 0.0.3: exact-pinned direct deps, min-release-age of 2 days, pre-commit lockfile guards, and published npm-shrinkwrap for transitive dependency control
- The MIT license and fully local execution model appeal to teams that cannot send source code or API keys through third-party SaaS
Problem it solves
- Multi-provider LLM integration is painful: OpenAI, Anthropic, and Google each expose different streaming formats, tool-calling conventions, and authentication mechanisms
- Terminal interfaces for real-time agent output need differential rendering—redrawing the full screen on every token stream is too slow for interactive use
- Agent loops require first-class tool calling, state persistence, and error recovery, not ad-hoc request/response plumbing
- Most local coding-agent tools under-document their security boundary, leaving operators surprised when the agent modifies files outside the workspace or executes shell commands with full user privileges
- Extending an agent with custom tools, skills, or providers often requires forking the core rather than plugging in an extension
How it works
- The published CLI package is @earendil-works/pi-coding-agent on npm. The monorepo root (pi-monorepo) is private with npm workspaces spanning all packages plus five example extension directories.
- When the user interacts with the coding agent, pi-agent-core manages the conversation loop: it dispatches LLM requests, processes tool-call responses, executes registered tools, and maintains agent state across turns.
- LLM requests route through pi-ai, which normalizes provider differences—streaming, tool schemas, system prompts—behind one interface for OpenAI, Anthropic, and Google.
- Terminal output is rendered by pi-tui using differential rendering: only lines that changed since the last frame are written to stdout, keeping the interface responsive during high-throughput token streaming.
- Extensions hook into the core without modifying it. The workspace's examples/extensions directory contains five examples: with-deps, custom-provider-anthropic, custom-provider-gitlab-duo, sandbox, and gondolin.
- Containerization is opt-in. Three patterns are documented in packages/coding-agent/docs/containerization.md: Gondolin (keep pi and provider auth on host, route tools into a micro-VM), plain Docker (full process isolation), and OpenShell (policy-controlled sandbox).
Package Architecture and Build Order
- @earendil-works/pi-ai (packages/ai): Unified multi-provider LLM API for OpenAI, Anthropic, and Google
- @earendil-works/pi-agent-core (packages/agent): Agent runtime with tool calling and state management
- @earendil-works/pi-coding-agent (packages/coding-agent): Interactive coding agent CLI—the user-facing entry point
- @earendil-works/pi-tui (packages/tui): Terminal UI library with differential rendering for high-throughput output
- The build script also references packages/orchestrator, which is built last after coding-agent but is not documented in the README package table
- Build order enforced by the monorepo: tui → ai → agent → coding-agent → orchestrator, reflecting a strict dependency chain
Try It Path: Build and Run From Source
- Prerequisite: Node.js >= 22.19.0 (enforced in package.json engines field)
- Install dependencies: npm install --ignore-scripts — the --ignore-scripts flag prevents lifecycle script execution during install, a supply-chain precaution
- Build all packages: npm run build — runs biome check with --write --error-on-warnings, then verifies pinned deps, TS relative imports, generated shrinkwrap, and a browser smoke test
- Run the full check suite: npm run check — includes lint, format, type checking via tsgo --noEmit, pinned-dependency verification, and shrinkwrap validation
- Run tests: ./test.sh — automatically skips LLM-dependent tests when API keys are not present in the environment
- Run pi from source without installing: ./pi-test.sh — can be executed from any directory
- Before submitting a PR, both npm run check and ./test.sh must pass
Security Trust Model: No Sandbox by Design
Pi's SECURITY.md defines a narrow, explicit trust boundary: the local user account and all files writable by that account are treated as inside the same trust boundary as the Pi process itself. If an attacker can modify files under the user's home directory, workspace, shell startup files, environment variables, or Pi configuration (including ~/.pi and ~/.pi/agent/models.json), they can influence Pi's behavior. Reports that depend on prior local write access are not treated as security vulnerabilities.
Prompt injection is explicitly out of scope. Files like AGENTS.md and instructions embedded in code comments can trivially prompt-inject the coding agent, and the project states this cannot be protected against. Users are expected to only run Pi within trusted repositories and to install trustworthy extensions and skills. Out-of-scope items also include untrusted MITM proxies, public internet exposure of a Pi installation, malicious model output, and user-approved local actions.
The project's answer to these constraints is containerization. packages/coding-agent/docs/containerization.md documents three patterns: Gondolin keeps pi and provider auth on the host while routing built-in tools and shell commands (! commands) into a local Linux micro-VM; plain Docker runs the entire pi process in a local container; OpenShell runs pi in a policy-controlled sandbox. None of these are built into the core—the core is minimal by design.
Contribution Model and Supply-Chain Hardening
- All issues and PRs from new contributors are auto-closed by default; maintainers review the queue daily and reopen items that meet the quality bar
- Two approval tiers: lgtmi (future issues won't be auto-closed) and lgtm (future issues and PRs won't be auto-closed); lgtmi does not grant PR rights
- Core is explicitly minimal—PRs that bloat the core will likely be rejected; features should be extensions, not core additions
- Contributors must understand their code: 'Submitting AI-generated slop without understanding it is not' acceptable
- Direct external dependencies are pinned to exact versions; internal workspace packages remain version-ranged
- .npmrc sets save-exact=true and min-release-age=2, blocking same-day dependency releases during npm resolution
- Pre-commit blocks accidental lockfile commits unless PI_ALLOW_LOCKFILE_CHANGE=1 is set
- The published CLI package includes packages/coding-agent/npm-shrinkwrap.json, generated from the root lockfile, to pin transitive deps for npm consumers
Who should pay attention?
Good fit if
- Building a custom agent that needs multi-provider LLM access without managing three different SDKs
- Replacing a hosted coding agent with a local-first CLI in a trusted repository
- Experimenting with agent extensions, custom providers, or sandboxing patterns using the five included example extensions
- Teams that need exact dependency pinning and supply-chain transparency in their agent tooling
Skip for now if
- Running the coding agent against untrusted repositories without a container or sandbox
- Production deployments that require a built-in permission system for filesystem, process, or network access
- Teams that need the project to accept community PRs quickly—the auto-close gate and lgtm requirement add latency
- Environments where Node.js >= 22.19.0 is not available
Risks and cautions
Pi has no built-in sandbox or permission system by design. Running the coding agent in an untrusted repository or with untrusted extensions grants the agent full user-level filesystem, process, and credential access. Containerization is the only mitigation, and it is the operator's responsibility.
- No sandbox in the core: the coding agent intentionally does not restrict filesystem, process, network, or credential access
- Prompt injection via AGENTS.md or code comments is acknowledged as unprotectable and explicitly out of scope
- Untrusted extensions, skills, packages, or tools can modify agent behavior—users must vet everything they install
- The project is at version 0.0.3 with a monorepo structure that includes an undocumented orchestrator package
- The contribution model auto-closes all new-contributor issues and PRs, which limits community-driven bug fixes in the short term
- SECURITY.md explicitly states the coding agent does not have a sandbox; local code execution is by design
- The trust boundary is the local user account—any file writable by the user can influence Pi's behavior
- Prompt injection attacks are out of scope and cannot be protected against per the project's own assessment
- Vulnerability reports must be sent privately to security@earendil.com or via GitHub Security Advisories; public issues for security reports are prohibited
- Supply-chain hardening includes exact-pinned direct deps, min-release-age=2, lockfile pre-commit guards, and published shrinkwrap for the CLI package
- npm install --ignore-scripts is the documented install command, preventing lifecycle script execution during dependency installation
Alternatives to compare
| Approach | When to use | Trade-off |
|---|---|---|
Aider | You want an established open-source coding agent with git integration and don't need a composable package architecture | Free, open-source (Apache 2.0) |
Open Interpreter | You want a general-purpose local code execution agent rather than a multi-package toolkit | Free, open-source (AGPL) |
Claude Code | You want a polished commercial coding agent from Anthropic with built-in safety features | Subscription-based, tied to Anthropic API pricing |
Vercel AI SDK | You need a multi-provider LLM library for web/edge runtimes and don't need a full agent loop or TUI | Free, open-source (Apache 2.0) |
What this trend reveals
Multi-provider LLM abstraction as a standalone dependency
@earendil-works/pi-ai can be consumed independently for projects that need normalized OpenAI/Anthropic/Google access without the agent runtime or TUI overhead.
The package is listed as a standalone workspace entry with its own build step in the monorepo build chain, and is published to npm separately.
Extension ecosystem for sandboxing
The Gondolin extension pattern—keeping auth on the host while routing tools into a micro-VM—could become a reference architecture for other local agent tools that need security boundaries.
The workspace includes examples/extensions/gondolin and examples/extensions/sandbox as concrete starting points, and containerization.md documents three patterns.
Differential-rendering TUI for non-agent terminal apps
@earendil-works/pi-tui's differential rendering is not specific to AI agents; any high-throughput terminal application could benefit from a library that only redraws changed lines.
The TUI package is built first in the dependency chain and has no dependency on the agent or AI packages.
RepoDaily verdict
Pi is a well-structured, honestly documented agent toolkit that puts the security burden on the operator by design. Its four-package architecture and exact-pinned supply chain make it a strong foundation for developers building local agent infrastructure—if they are willing to manage their own sandbox.