pi-arcweld

Don't fork it. Weld it.

An auditable local workspace for the Pi coding agent:
pinned upstream source, curated extensions, bounded MCP tooling, and a reproducible runtime.

What is pi-arcweld?

pi-arcweld is an auditable local workspace for the Pi coding agent. It welds a curated local layer of user extensions, global system guidance, bounded MCP tooling, and a reproducible runtime onto pinned upstream Pi source, along one visible seam. Pi Arcweld is not a fork: upstream stays upstream, and the workspace stays yours.

Why weld instead of fork?

• Pinned upstream, no drift. pi-mono/ is a submodule locked to a known commit; moving to a newer Pi is an explicit, reviewable fast-forward.
• One visible seam. Every local behavior, from extensions and MCP wiring to system guidance, is a plain file in this repository, so changes surface in git diff, not in hidden machine state.
• Reproducible runtime. scripts/build-pi-agent.sh assembles and verifies the runnable Pi agent outside the upstream tree; pi-mono/ never accumulates build state.
• Bounded tooling, guarded secrets. MCP servers run as separate stdio processes, and scripts/check-secret-boundary.sh fails any commit that would leak credentials into the repository.

Curated components

• External runtime builder: assembles and verifies Pi without writing build state into upstream source.
• Cache-safe plan mode: appends plan state while preserving the provider prompt-cache prefix.
• Native Pi MCP: discovers tools on demand through codemode, with fixed server descriptions and stable model-facing declarations.
• Questionnaire: presents explicit, keyboard-operable clarification flows.
• System-instruction append: refines response behavior without replacing Pi's generated system prompt.

Repository layout

Path	Contents
pi-mono/	Pinned upstream Pi source, managed as a Git submodule and kept clean of local build state
extensions/	Curated user-level Pi extensions and package-backed extensions
mcp-servers/	Canonical source for local MCP servers, deployed as tested versioned releases under ~/.local/mcps/
system-instruction/	The global APPEND_SYSTEM.md source and capture notes
scripts/	Runtime build, upstream-update, and validation scripts
Website source	Independent landing page, assets, and discovery files maintained in the frontend repository
build/	Generated local runtime and package artifacts, intentionally untracked

Quickstart

Clone the repository with its pinned upstream submodule:

git clone --recurse-submodules https://github.com/appautomaton/pi-arcweld.git pi-arcweld
cd pi-arcweld

Build and link the local Pi runtime without writing build output into pi-mono/:

scripts/build-pi-agent.sh --link-user-bin
pi --version

The build prefers the repository's pinned native tsgo compiler when it is runnable and otherwise falls back to the pinned tsc compiler, targeting ES2024 because the TUI source uses the RegExp v flag. Compiler selection is capability-based and requires no platform-specific source branches.

Restore the existing check tools, then validate the repository and machine wiring:

npm ci --ignore-scripts --prefix scripts/checks
scripts/check-workspace.sh
scripts/check-user-wiring.sh

Updating Pi

Read the upstream coding-agent changelog and model API changelog for changes to extension events, tool exposure, provider protocols, and usage accounting. The update helper realigns pi-mono onto upstream main, rebuilds the runtime, and runs the existing extension compatibility checks. Upstream rewrites and force-pushes main, and this checkout is a depth=1 shallow clone, so the helper falls back to resetting onto the fetched tip when a fast-forward is not possible. It re-verifies a clean pi-mono worktree before doing so, and never commits or pushes:

scripts/update-pi-mono.sh
git diff --submodule=log -- pi-mono

The helper never commits or pushes. Review the resulting submodule pointer before committing it in this repository.

User-level integration

The active Pi configuration uses explicit user-level wiring: extensions point to canonical repository source, while the Camoufox MCP runs from a tested local deployment:

• ~/.pi/agent/extensions/plan-mode → extensions/plan-mode/
• ~/.pi/agent/extensions/questionnaire.ts → extensions/questionnaire.ts
• ~/.pi/agent/extensions/vibrant-footer.ts → extensions/vibrant-footer.ts
• ~/.pi/agent/extensions/exa-search.ts → extensions/exa-search.ts
• ~/.pi/agent/extensions/codex-web-search.ts → extensions/codex-web-search.ts
• ~/.pi/agent/extensions/claude-web-search → extensions/claude-web-search/
• ~/.pi/agent/extensions/grok-search.ts → extensions/grok-search.ts (optional)
• ~/.pi/agent/APPEND_SYSTEM.md → system-instruction/APPEND_SYSTEM.md
• Native Pi MCP reads mcpServers in ~/.pi/agent/mcp.json; no local MCP client package is registered
• ~/.pi/agent/mcp.json runs the deployed Camoufox MCP at ~/.local/mcps/camoufox/current/bin/camoufox-mcp (optional; its browser payload is machine-local, so scripts/check-user-wiring.sh validates the deployment where it exists and reports it as absent otherwise)
• the user pi command resolves to build/pi-agent/runtime/bin/pi

MCP servers use exposure: "codemode" and fixed one-line descriptions. Tools are discovered with searchTools() and called inside codemode scripts; they are not added individually to the main request. Fixed descriptions prevent startup discovery from rewriting the leading prompt on providers without mid-conversation system-message support. Native MCP inherits the Pi process environment; the former client used a restricted environment and private mcp.env interpolation.

The default model provider is the local CPA server at http://127.0.0.1:5233/: GPT uses /v1, and Gemini uses /v1beta. Credentials remain machine-local. Registering MCP servers does not change model routing.

Secret boundary

Machine-local settings, credentials, and unrelated user extensions are not stored in this repository. The Exa API key stays only in ~/.pi/agent/exa-search.json, and Grok provider credentials stay in Pi's machine-local model/auth configuration. scripts/check-secret-boundary.sh fails if commit candidates include Pi credential or config files, obvious literal secrets, or an exact credential value discoverable from the active machine-local Pi configuration.

Development model

The repository intentionally has no root package.json or shared npm workspace. Each local package owns its manifest and checks, and upstream Pi retains its own build and release process. Only packages with real third-party runtime dependencies carry a lockfile; source-only extensions declare Pi packages as wildcard peer dependencies and are type-checked and tested against the live built runtime, so no local manifest pins a Pi version that could go stale on an upstream update. The root repository records the upstream URL and pinned Pi commit, not local Pi source changes. See AGENTS.md for workspace, build, and Git hygiene rules.

Links

• Project site: appautomaton.com/pi-arcweld
• Repository: github.com/appautomaton/pi-arcweld
• Upstream Pi: pi.dev · github.com/earendil-works/pi
• Maintainer: App Automaton · appautomaton.com

---

_{Pi Arcweld is maintained by App Automaton. The Pi coding agent is developed upstream by earendil-works.}