pi - Moses Yebei

The Problem

Teams building AI agents face two recurring problems: every LLM provider has its own API shape, and every agent loop reinvents tool calling, session state, and prompt management. Pi consolidates both into a single TypeScript monorepo—one unified provider layer, one agent runtime, and one coding-agent CLI that is itself extensible via plugins.

What This Does

The repo is a monorepo of five npm packages under packages/. packages/ai is a multi-provider LLM client (OpenAI, Anthropic, Google, Bedrock, Mistral, OpenRouter, and others) with OAuth flows, credential storage, and model catalogs. packages/agent provides the agent runtime: a session harness, tool-calling loop, compaction, and JSONL session persistence. packages/coding-agent is the interactive TUI/CLI that ties it together, with packages/tui handling terminal rendering and packages/telemetry providing vendor-neutral event schemas.

The README is explicit that Pi has no built-in permission system—it runs with the launching user's privileges. The repo documents three containerization patterns (Gondolin micro-VM, plain Docker, OpenShell sandbox) rather than baking sandboxing into the core.

How It Is Wired

Execution starts at the CLI entry point in packages/coding-agent/src/index.ts, which routes through packages/coding-agent/src/modes/interactive/interactive-mode.ts (the main loop). That mode delegates to packages/coding-agent/src/core/session-manager.ts for session lifecycle and packages/coding-agent/src/core/settings-manager.ts for configuration. The agent loop itself lives in packages/agent/src/agent-loop.ts, which calls the packages/ai provider layer. Network effects are concentrated in packages/ai/src/api/*.ts (one file per provider) and packages/ai/src/auth/oauth/*.ts for credential flows; filesystem effects go through packages/agent/src/harness/tools/{read,write,edit,bash}.ts.

The import graph is healthy overall: 1,180 internal modules, 3,191 edges, and only 75 modules inside circular dependencies. The hub is packages/ai/src/types.ts (167 modules depend on it), followed by packages/coding-agent/src/modes/interactive/theme/theme.ts (97 dependents). The critical cycle is packages/ai/src/types.ts ↔ packages/ai/src/models.ts; breaking it requires extracting shared types. The interactive-mode.ts file is in a cycle too and has high instability (0.76), meaning changes there ripple widely.

How To Use It

Setup: npm install --ignore-scripts then npm run build (per the README). The repo uses npm workspaces; there is no Dockerfile.

Configuration: Provider keys go through the OAuth flows in packages/ai/src/auth/ or environment variables handled by packages/ai/src/env-api-keys.ts. No central config file is present; settings are managed at runtime by settings-manager.ts.

Running it: ./pi-test.sh runs from source. For standalone binaries, extract the release source archive and run ./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out" (both commands verbatim from the README).

Real-World Use

A team standardizing on Pi can write one agent loop and swap providers per environment: packages/ai/src/api/openai-responses.ts for OpenAI in CI, packages/ai/src/api/bedrock-converse-stream.ts for Bedrock in production, and packages/ai/src/api/google-vertex.ts for GCP. The coding agent's extension mechanism (see packages/coding-agent/examples/extensions/) lets a team add a custom provider or sandbox without forking the core.

Code Health & Issues

Static analysis found 603 findings (205 high, 396 medium). The high-severity clusters: 14 import-cycle members (notably packages/ai/src/types.ts, packages/ai/src/models.ts), 13 oversized files (largest is packages/ai/src/types.ts at 611 lines), 17 deep-nesting cases (max depth 9 in packages/ai/src/models.ts), and 13 hub modules with high blast radius. These are real maintenance costs, not style nits.

The security audit found one critical issue: .github/workflows/publish-model-catalog.yml has R2 credentials in a workflow that can be triggered by fork PRs—move secret-using steps into a workflow_run job. Medium issues: no permissions: declaration in ci.yml, no Dependabot/Renovate, and persist-credentials: false missing on checkout. Low: no job timeouts in build-binaries.yml. The repo has 552 test files, CI, a license, and a lockfile; no committed secrets found.

The Bottom Line

Pi is a serious, well-structured agent toolkit with real breadth—five packages, 27 dependencies, and 552 tests. The provider abstraction and agent runtime are production-grade, but the hub modules and cycles in packages/ai will make deep changes expensive. Teams wanting a multi-provider agent foundation should evaluate it; teams needing sandboxing out of the box should look elsewhere or adopt the documented containerization patterns.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,390 files

TypeScript1151
Markdown97
JSON47
YAML14
Shell8
JavaScript6

ReactTransformersCUDA

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["packages<br/>1145 modules"] g1["scripts<br/>30 modules"] g2[".pi<br/>4 modules"] g1 -->|4| g0

Module dependencies

The 10 most depended-upon modules of 1,180, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_packages_ai_src_types["types"] n1_odes_interactive_theme_theme["theme"] n2_packages_ai_src_compat["compat"] n3_ent_src_core_session_manager["session-manager"] n4_packages_ai_src_models["models"] n5_nt_src_core_settings_manager["settings-manager"] n6_ages_coding_agent_src_config["config"] n7_ing_agent_test_suite_harness["harness"] n8__agent_src_core_auth_storage["auth-storage"] n9_nt_src_core_extensions_types["types"] n2_packages_ai_src_compat --> n4_packages_ai_src_models n2_packages_ai_src_compat --> n0_packages_ai_src_types n4_packages_ai_src_models --> n0_packages_ai_src_types n8__agent_src_core_auth_storage --> n6_ages_coding_agent_src_config n9_nt_src_core_extensions_types --> n1_odes_interactive_theme_theme n9_nt_src_core_extensions_types --> n3_ent_src_core_session_manager n3_ent_src_core_session_manager --> n6_ages_coding_agent_src_config n5_nt_src_core_settings_manager --> n6_ages_coding_agent_src_config n1_odes_interactive_theme_theme --> n6_ages_coding_agent_src_config n7_ing_agent_test_suite_harness --> n8__agent_src_core_auth_storage n7_ing_agent_test_suite_harness --> n3_ent_src_core_session_manager n7_ing_agent_test_suite_harness --> n5_nt_src_core_settings_manager classDef cyc stroke:#ef4444,stroke-width:2px; class n0_packages_ai_src_types,n4_packages_ai_src_models,n9_nt_src_core_extensions_types cyc;

Dependencies

7 of 27 declared dependencies are a major version behind. Resolved 27 of 27 against the registry.

Package	Declared	Latest	Behind
`@types/node`	22.19.19	26.2.0	4 major
`typescript`	5.9.3	7.0.2	2 major
`http-proxy-agent`	7.0.2	9.1.0	2 major
`https-proxy-agent`	7.0.6	9.1.0	2 major
`diff`	8.0.4	9.0.0	1 major
`@google/genai`	1.52.0	2.17.1	1 major
`openai`	6.40.0	7.4.0	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical1

medium3

low1

Keep secrets out of workflows a fork can triggercritical2 occurrences

.github/workflows/publish-model-catalog.yml

PI_ARTIFACTS_R2_ACCESS_KEY_ID, PI_ARTIFACTS_R2_SECRET_ACCESS_KEY

Contributor-controlled input reaches a job holding a publish token or cloud credential, so a pull request becomes credential exfiltration.

Fix: Move secret-using steps into a workflow_run job that never checks out pull request code, or gate on an environment with required reviewers.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

12 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/build-binaries.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.