my-pi

Local-first MCP runtime for coding agents — safer workspace access without an unrestricted shell
_{Bounded filesystem · content-preconditioned writes · Tree-Sitter AST search · LSP navigation · Git tooling}

What is my-pi?

my-pi is a deterministic local coding capability runtime exposed through the official Model Context Protocol (MCP). It gives MCP-capable coding agents controlled access to a real workspace through explicit workspace authority, bounded reads, guarded writes, structural search, language-server intelligence, and Git operations.

It is aimed at developers who want agentic coding tools to understand and modify code without handing the agent a general-purpose shell or silently granting the current working directory.

Why use it?

• Local-first: source code and detailed workspace state remain on the host.
• Read-only by default: writes and language-server process startup require explicit trusted elevation.
• Safer mutation: writes can require SHA-256 content preconditions instead of blind overwrite semantics.
• Code-aware search: Tree-Sitter structural search across TypeScript, JavaScript, Python, Rust, and Go.
• Semantic navigation: LSP symbols, definitions, references, hover, and diagnostics for supported host language servers.
• Git-aware context: bounded status and diff operations with secret filtering and large-diff spillover.
• No secondary paid LLM dependency: the core runtime executes locally and does not select models or spawn agents.

Release channel: Alpha. The npm badge above is authoritative for the currently published package version. This repository may contain a newer release candidate before publication completes. Suitable for evaluation and controlled local development; review the security model before enabling the trusted profile.

Install in under a minute

Requires Node.js >=24.0.0 (Node 24 LTS is the normative runtime).

npm install -g @koonwang03/my-pi
my-pi-mcp --workspace /path/to/your/project

The server starts read-only. For a workspace you explicitly trust:

my-pi-mcp --workspace /path/to/your/project --security-profile trusted

Or inspect a host configuration without a global install:

npx --yes --package @koonwang03/my-pi my-pi-mcp host-config cursor-local

Generate host-specific configuration snippets:

my-pi-mcp host-config claude-code-local
my-pi-mcp host-config cursor-local
my-pi-mcp host-config opencode-current-local

Starting without --workspace or MY_PI_WORKSPACE_ROOT fails closed. Use --allow-cwd only when granting the current directory is intentional.

The published npm package is the stable MCP server. The coordination daemon and local UI are private workspace packages used by the experimental source build; build the repository before using those components.

13-tool MCP surface

Key guarantees

Architecture

MCP-capable coding host
        │
        │ stdio
        ▼
┌─────────────────────┐
│   my-pi MCP edge    │
└──────────┬──────────┘
           ▼
┌─────────────────────┐
│ capability contracts│
└──────────┬──────────┘
           ▼
┌─────────────────────────────────────────────────────────┐
│ workspace │ policy │ filesystem │ search │ AST │ LSP │ Git │
└─────────────────────────────────────────────────────────┘
           │
           └── local host workspace

The stable public claim is the 13-tool MCP capability surface. The repository also contains two opt-in candidates that never change the default mode:

• Production Next — coordination, code-state, change-receipt, evaluation, and feedback features, subject to their promotion gates.
• Visual Plane — a read-only graph/theater projection of authoritative local state, plus a mutation-provenance and local-admission path.

Build from source

git clone https://github.com/BoxBoxmari/my-pi.git
cd my-pi
pnpm install --frozen-lockfile
pnpm build

Prerequisites for repository development:

• Node.js v24.0.0+ (Node 24 LTS normative; exact-minimum 24.0.0 lane is qualified in CI)
• pnpm v11.2.2+
• Rust stable is optional and currently relevant only to the deferred native-backend scaffold

Verification

# Local code, architecture, boundary, build, tests, gates and smoke verification
pnpm verify

# Unit/integration suite
pnpm test

# SBOM validation
pnpm verify:sbom

# Release admission checks
pnpm bind:evidence
pnpm verify:release

The configured CI matrix covers Ubuntu, Windows, and macOS lanes. See the live workflow badges above for current status rather than relying on static claims in this document.

Engineering contracts

Benchmarks

The repository contains deterministic synthetic benchmarks for MCP stdio overhead, search/traversal throughput, memory sampling, runtime boundaries, coordination behavior, impact routing, evaluation feedback, and local reliability. Benchmark outputs are candidate evidence; performance claims should be interpreted alongside their qualification criteria and runner variance.

Self-hosted tracks and promotion

The self-hosted program keeps implementation, measurement, and promotion as separate decisions:

• Track A — evidence harness: ObservedTask v2 tasks are committed and receipt-bound before a run. Control and treatment arms use isolated worktrees, independent downstream adjudication, and fail-closed aggregation.
• Track B — enforcement: mutation provenance, local admission, portable attestation, and host policy bundles distinguish managed changes from unmanaged or review-required changes. Report-mode results do not imply strict host enforcement.
• Track C — visual plane: the graph and theater views project authoritative local state through the daemon, loopback portal, or opt-in MCP Apps resources. These views do not change the default 13-tool catalog.

The current evidence files under evidence/ are candidate-bound records, not a release or promotion claim. A passing test, a qualified sample, or an accepted individual evidence record does not by itself open PN11. Use the read-only promotion verifier as the authority:

pnpm verify:observed-v2
pnpm verify:production-next-evidence
pnpm verify:production-next-promotion