my-pi is a local-first MCP runtime for coding agents that exposes capabilities through the official Model Context Protocol (MCP). It allows MCP-capable coding agents to access a real workspace in a controlled way without needing general shell permissions and without silently granting the current working directory.
Main capabilities:
- Local-first: source code and detailed workspace state remain local to the host.
- Read-only by default: writes and language server process startup require explicit trusted elevation.
- Safer changes: writes can require a SHA-256 content precondition instead of blind overwrite semantics.
- Code-aware search: Tree-Sitter-based structured search covering TypeScript, JavaScript, Python, Rust, and Go.
- Semantic navigation: LSP symbols, definitions, references, hover, and diagnostics on supported host language servers.
- Git-aware context: bounded status and diff operations, with secret filtering and large-diff overflow handling.
- No secondary paid LLM dependency: the core runtime executes locally, does not select models, and does not spawn agents.
Usage: Requires Node.js >= 24.0.0 (Node 24 LTS is the canonical runtime). The server starts in read-only mode. For explicitly trusted workspaces, it can be installed via npm and configured with a host. Startup fails closed when --workspace or MY_PI_WORKSPACE_ROOT is not provided; use --allow-cwd only when intentionally granting the current directory. The published npm package is a stable MCP server; the coordination daemon and local UI are private workspace packages for experimental source builds, and the repository must be built before use. Host-specific configuration snippets can be generated from the command line, and host configuration can be inspected without a global install.
MCP capability surface: The stable public declaration is a 13-tool MCP capability surface. The repository also contains two optional candidates, and they do not change the default mode: Production Next (coordination, code state, change receipts, evaluation, and feedback features, subject to its promotion gates) and Visual Plane (a read-only graph/theater projection of authoritative local state, as well as change provenance and local admission paths).
Building from source: The development prerequisite is Node.js v24.0.0+ (Node 24 LTS is the specification, with the exact minimum 24.0.0 verified in CI), Rust stable is optional and currently only relevant to the deferred native backend scaffolding. The CI matrix covers Ubuntu, Windows, and macOS.
Engineering contract and self-hosting track: 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 output is candidate evidence, and performance claims must be interpreted in light of their qualification criteria and runner differences. The self-hosting plan treats implementation, measurement, and promotion as separate decisions, comprising Track A (evidence framework), Track B (enforcement), and Track C (visualization plane). Evidence files under evidence/ are candidate binding records, not release or promotion claims; the read-only promotion validator is the authoritative basis, and unless the final command reports promotionEligible: true, PN11 should remain failed.
Experimental features:
- Production Next: can start a local coordination candidate, adding --evaluation only when an evaluation plane is needed. The candidate keeps source code and detailed code state local, does not select models, does not spawn agents, and does not require a hosted control plane.
- Visual Plane: an optional read-only visualization plane that renders authoritative local state as a bounded graph; it is a projection of coordination graph snapshots and event logs, not an LLM-generated graph, and never modifies source state. Agent Operations Theater renders a Three.js isometric work graph (agents, work items, intents, dependencies), with live event hints, a replay timeline, evidence/trace/provenance inspectors, and automatic fallback to 2D SVG when WebGL is unavailable. It honestly exposes data states such as degraded, truncated, stale, and empty; unknown event types do not drive animation; sensitive paths embedded in free-text values are redacted at every wire egress. The portal binds only to the loopback address and requires a per-launch session token, and is read-only in V1. The default MCP catalog remains exactly 13 tools.
- Change provenance and local admission: observation mode targets verified my-pi change receipts, classifying observed code state transitions as managed, unmanaged, stale_lineage, unknown, or exempt; external edits never become managed merely by observing final bytes. Local admission compares a Git changeset against verified lineage, returning path-level allowed / rejected / review_required results. Portable proof: the canonical cross-platform admission subject digest can be signed with Ed25519 (the private key is stored outside the workspace) and verified in CI without local SQLite state. Host policy packs declare each host's enforcement maturity (strict-capable / managed / monitoring), and a configuration is never marked strict-certified without planted bypass evidence.
Applicable scenarios and limitations: Suitable for developers who want agentic coding tools to understand and modify code but are unwilling to hand over a general-purpose shell or silently authorize the current working directory, and for evaluation and controlled local development. The current release channel is Alpha; docs/SECURITY_MODEL.md should be read before using trusted mode, and search ignore behavior is described in docs/SEARCH_IGNORE.md (it is a traversal optimization and cannot replace sensitive path policy). Specific information about fees, pricing, and platform support is not currently provided in the materials.
