Pi: Unified multi-provider LLM API and extensible coding-agent CLI
Pi is a multi-model coding-agent CLI for developers, combining tool calling and TUI while leaving isolation to Docker or sandboxes.
GitHub earendil-works/pi Updated 2026-09-04 Branch main Stars 100.0K Forks 12.4K
LLM API AI agent pi-coding-agent Terminal UI Linux micro-VM Docker OpenShell

🧭 Decision Guide

Why trending now: Cannot be determined from the provided materials.

Try it if you

  • You need one LLM interface across providers such as OpenAI, Anthropic, and Google.
    README, All Packages: pi-ai is a “Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.).”
  • You need a coding agent with tool calling, state management, and a terminal interface.
    README, All Packages: pi-agent-core provides tool calling and state management; pi-coding-agent is an interactive coding-agent CLI; pi-tui is a terminal UI library.
  • You can run Pi inside a Docker container, Gondolin Linux micro-VM, or OpenShell sandbox.
    README, Permissions & Containerization lists Gondolin, Plain Docker, and OpenShell as three patterns.
  • You need an MIT-licensed open-source AI agent toolkit.
    The License section states MIT; project metadata describes it as an AI agent toolkit.

Skip it if you

  • You require Pi itself to restrict filesystem, process, network, or credential access.
    README, Permissions & Containerization explicitly says, “Pi does not include a built-in permission system.”
  • You cannot provide model API keys but need the complete LLM-dependent test suite.
    README, Development: `./test.sh` skips LLM-dependent tests without API keys.
  • Your team expects public issues and PRs from new contributors to enter community processing immediately.
    The README states that issues and PRs from new contributors are auto-closed by default.

Requirements

  • The Development section provides `npm install --ignore-scripts`, indicating npm is used for development dependency installation.
  • The build process uses `npm run build`, which refreshes model data and builds all packages.
  • API keys are required for LLM-dependent tests; `./test.sh` skips those tests without keys.
  • For stronger boundaries, the README points to Gondolin, Plain Docker, or OpenShell rather than a built-in Pi permission system.
  • The standalone-binary build script uses a Bun executable, but the README does not specify a required Bun version.

First step (verbatim from README)

npm install --ignore-scripts  # Install all dependencies without running lifecycle scripts

Watch out

  • When Pi runs directly, its built-in behavior does not reduce the launching user's filesystem, process, network, or credential permissions.
    README, Permissions & Containerization says Pi inherits user and process permissions by default and recommends containerizing or sandboxing it.
  • When running `./test.sh`, LLM-dependent tests are skipped if API keys are unavailable.
    The Development command comment says it skips LLM-dependent tests without API keys.
  • With `--offline-model-data`, standalone builds use the provider-model-data snapshot contained in the source archive.
    README, Building standalone binaries from release source says the option uses the archive snapshot instead of live provider catalogs.
  • Dependency installation skips lifecycle scripts by default, and new lifecycle-script dependencies fail checks until reviewed.
    README, Supply-chain hardening specifies `npm ci --ignore-scripts` and review requirements for new lifecycle-script dependencies.

Alternatives

  • earendil-works/pi-chat：Use it when the goal is Slack/chat automation and workflows rather than an interactive coding-agent CLI.
    README, All Packages: “For Slack/chat automation and workflows see earendil-works/pi-chat.”
  • Plain Docker：Use it when you only need the entire Pi process in a local container and do not need Gondolin's host-authentication arrangement.
    README, Permissions & Containerization.
  • OpenShell：Use it when you need a policy-controlled sandbox rather than basic local Docker isolation.
    README, Permissions & Containerization.

Not stated in the README

  • The README does not specify supported Node.js, npm, or Bun versions.
  • The README does not describe authentication setup or required environment variables for OpenAI, Anthropic, or Google.
  • The README does not provide the complete end-user installation command or available CLI arguments for pi-coding-agent.
  • The README does not state CPU, memory, or disk requirements for the Linux micro-VM, Docker, or OpenShell options.
  • The main-language distribution is empty in the project data, and the technology stack is marked Mixed/Unknown.
  • Project data provides no recent-update date; development activity shows 0 contributors, 0 releases, and 0 recent commits.
  • The README does not document production use cases or performance metrics behind the 101,642 stars.
  • The README does not specify the agent loop's maximum context, tool protocol, retry policy, or concurrency model.

💡 Deep Analysis

6
No I am responsible for Slack chat automation and workflows, not terminal-based code-modification agents. Should Pi be my primary project dependency?
For: An application developer who wants AI agents integrated into Slack chat automation and workflows rather than running as a terminal coding agent

No, not as the primary entry point, because the README explicitly directs Slack, chat automation, and workflow use cases to the separate pi-chat project.

  • Pi is positioned as a “unified LLM API, agent loop, TUI, coding agent CLI,” emphasizing the runtime, terminal UI, and interactive coding agent.
  • The package list includes pi-coding-agent, pi-agent-core, pi-ai, pi-tui, chord, and pi-telemetry, but no Slack adapter as part of Pi.
  • The README explicitly says: “For Slack/chat automation and workflows see earendil-works/pi-chat.”

You may still reuse pi-ai or pi-agent-core if the application needs those abstractions. However, do not assume Pi provides Slack event ingestion, message delivery, workflow triggers, or their permission model. The README does not describe the interface or version relationship between Pi and pi-chat.

  • README project description: "unified LLM API, agent loop, TUI, coding agent CLI"
  • All Packages: the listed packages do not include a Slack adapter
  • All Packages: "For Slack/chat automation and workflows see earendil-works/pi-chat"
Not stated in the README：The README does not describe the integration interface, version compatibility, or feature boundary between Pi and pi-chat.；It does not document Slack events, identity authentication, message delivery, or workflow orchestration capabilities.
No I plan to let the coding agent perform filesystem, process, and network operations, but the environment must have an explicit isolation boundary. Can I run untrusted agent tasks directly after installing Pi with its defaults?
For: A security engineer whose agent must perform filesystem, process, and network operations under a local Linux micro-VM, Docker, or OpenShell boundary

No, because Pi does not provide a built-in permission system restricting filesystem, process, network, or credential access.

  • The README explicitly says that Pi runs with the permissions of the user and process that launched it by default; this is not a boundary for untrusted tasks.
  • It documents three isolation paths: Gondolin routes built-in tools and ! commands into a local Linux micro-VM, Docker isolates the whole Pi process, and OpenShell provides a policy-controlled sandbox.
  • Therefore, untrusted tasks, code, or extensions require containerization or sandboxing as part of deployment rather than relying on the CLI alone.

The README does not compare syscall coverage, network policy, performance overhead, or credential exposure among the three options. It also does not explain how custom tools inherit the same boundary.

  • Permissions & Containerization: "Pi does not include a built-in permission system"
  • Permissions & Containerization: "By default, it runs with the permissions of the user and process that launched it"
  • Permissions & Containerization: "Gondolin extension", "Plain Docker", and "OpenShell"
Not stated in the README：The README provides no permission matrix, default network policy, or performance data for Gondolin, Docker, and OpenShell.；It does not specify how custom tools, plugins, or provider authentication behave across the isolation boundary.
Yes I need to install Pi's npm CLI internally with exact dependency pinning, lifecycle scripts disabled by default, and auditable release artifacts. Do the controls described in the README match this constraint?
For: A release or platform engineer installing the npm CLI internally who must review dependency lifecycle scripts and run supply-chain audits

Yes, because the README defines explicit mechanisms for dependency pinning, script control, shrinkwrap, and auditing.

  • Direct external dependencies use exact versions; package-lock.json is the dependency source of truth, and the published CLI includes an npm-shrinkwrap.json generated from it.
  • .npmrc sets save-exact=true and min-release-age=2, reducing exposure to same-day dependency releases.
  • CI uses npm ci --ignore-scripts; local release installs, documented npm installs, and pi update --self also use --ignore-scripts where supported.
  • A scheduled workflow runs npm audit --omit=dev and npm audit signatures --omit=dev, while lifecycle scripts require an explicit allowlist review.

However, the README does not specify an internal artifact repository, signature-verification workflow, vulnerability SLA, or exception-approval process. Those need to come from platform policy.

  • Supply-chain hardening: "Direct external dependencies are pinned to exact versions"
  • Supply-chain hardening: "package-lock.json is the dependency ground truth"
  • Supply-chain hardening: "CI installs with npm ci --ignore-scripts"
  • Supply-chain hardening: "npm audit --omit=dev" plus "npm audit signatures --omit=dev"
npm install --ignore-scripts
Not stated in the README：The README does not specify an internal npm registry, release-signature verification, or artifact-retention process.；It does not define vulnerability-fix timelines, dependency-upgrade exceptions, or blocking rules after audit failures.
Yes I need to build a standalone linux-x64 binary from the GitHub release source on a machine without network access, while reusing the model data shipped with the release. Does Pi support this constraint?
For: A release engineer who needs to build a standalone linux-x64 binary from release source on a machine without network access

Yes, because the README explicitly documents an offline standalone-binary build using model data shipped with the release.

  • GitHub releases provide a versioned source archive covered by SHA256SUMS, allowing the source archive to be verified first.
  • The archive includes generated provider model data used for the release, and --offline-model-data avoids refreshing live provider catalogs.
  • The documented script supports --platform linux-x64 --out and builds the monorepo, compiles the Bun executable, and stages runtime assets.
  • If dependencies are supplied separately, the script also supports --skip-install --skip-deps.

The offline mode primarily avoids refreshing model data. The README still says the script installs dependencies unless they are supplied separately. It does not specify required Bun/npm versions or the complete offline dependency-cache format.

  • Building standalone binaries from release source: "The source archive includes the generated provider model data"
  • Building standalone binaries from release source: "--offline-model-data"
  • Documented command: "./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out \"$PWD/out\""
  • Building standalone binaries from release source: "--skip-install --skip-deps"
./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out"
Not stated in the README：The README does not specify the Bun/npm versions or the pre-provisioned dependency directory layout required for offline builds.；It does not document the complete supply-chain procedure for initially obtaining the source archive, dependencies, and model data.
Yes I want to use an interactive coding agent in the terminal for code changes and debugging while retaining the ability to switch among OpenAI, Anthropic, and Google providers. Is Pi suitable for this workflow?
For: A software developer who needs terminal-based AI coding and debugging, while switching between OpenAI, Anthropic, and Google models

Yes, because Pi combines a terminal coding agent with a unified multi-provider LLM interface.

  • pi-coding-agent is described as an interactive coding agent CLI for terminal-based coding sessions.
  • pi-ai provides one API for OpenAI, Anthropic, Google, and other providers, reducing provider-specific integration work.
  • pi-agent-core includes tool calling and state management, which supports multi-turn executable coding tasks.

The unified interface does not make model tool behavior, context limits, or coding quality identical. The README also does not specify the exact model catalog, credential configuration, or model-switching command. If running from source, it provides installation, build, and test commands.

  • All Packages: "Interactive coding agent CLI"
  • All Packages: "Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.)"
  • All Packages: "Agent runtime with tool calling and state management"
npm install --ignore-scripts
Not stated in the README：The README does not specify credential configuration, the available model catalog, or runtime switching procedures for each provider.；The compatibility boundaries for tool calling and context capabilities across providers are not documented.
Yes I need to build custom tool-calling, multi-turn stateful agent flows on top of a unified LLM API, but I do not want to bind my application to the interactive coding CLI. Which Pi packages should I use?
For: An engineer building custom agents and tool-calling workflows who wants to reuse a runtime instead of rebuilding around a fixed CLI

Yes, because Pi separates LLM access, the agent runtime, and the terminal UI into reusable packages rather than exposing only a fixed CLI.

  • pi-ai provides the unified multi-provider LLM API and can serve as the model integration layer.
  • pi-agent-core explicitly provides the agent runtime, tool calling, and state management needed for custom workflows.
  • pi-coding-agent is the interactive CLI and is an upper-layer usage option, not the only way to reuse the runtime.
  • For services, replicated state, RPC, or plugins, the README lists chord; telemetry needs can use pi-telemetry.

The trade-off is that you must understand package boundaries, state lifecycles, error propagation, and compatibility. The README does not provide a complete custom-tool API example or stability guarantees for each package.

  • All Packages: "Unified multi-provider LLM API"
  • All Packages: "Agent runtime with tool calling and state management"
  • All Packages: "Standalone application-composition runtime for services, replicated state, RPC, and plugins"
  • All Packages: "Vendor-neutral telemetry contracts, reference adapter, conformance tests, and typed schemas"
npm run check
Not stated in the README：The README does not document the detailed programming interfaces for custom tools, agent loops, or state management.；It does not define compatibility policies or stable API boundaries between workspace packages.

✨ Highlights

  • pi-ai unifies access to OpenAI, Anthropic, Google, and other models
  • pi-agent-core provides an agent runtime with tool calling and state management
  • pi-coding-agent provides an interactive coding-agent CLI
  • By default, Pi inherits user-process permissions and has no built-in permission system
  • MIT-licensed with more than 101,000 GitHub stars

🔧 Engineering

  • pi-ai unifies multi-provider LLM APIs including OpenAI, Anthropic, and Google
  • pi-agent-core manages tool calling, agent execution, and state
  • pi-coding-agent uses pi-tui to provide an interactive terminal coding agent
  • Gondolin, Docker, and OpenShell provide three isolation paths

⚠️ Risks

  • The README states that Pi has the launching process's filesystem, process, and network permissions by default
  • Issues and PRs from new contributors are auto-closed by default and reviewed daily
  • LLM-dependent tests are skipped by ./test.sh when API keys are unavailable
  • Project metadata reports 0 contributors and 0 releases

👥 For who?

  • LLM application developers who need to switch among OpenAI, Anthropic, and Google
  • Teams needing a terminal coding agent, tool calling, and state management
  • Users who can provide Docker, a Linux micro-VM, or an OpenShell sandbox