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.
• MCP client: discovers configured servers behind a fixed, bounded model-facing tool surface.
• 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/	Local MCP servers the client launches over stdio, such as camoufox/
system-instruction/	The global APPEND_SYSTEM.md source and capture notes
scripts/	Runtime build, upstream-update, and validation scripts
docs/	The pi arcweld landing page, llms.txt, and sitemap served by GitHub Pages
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.

Validate the repository and machine wiring:

scripts/check-workspace.sh
scripts/check-user-wiring.sh

Updating Pi

Fast-forward the local pi-mono checkout to upstream main and rebuild the runtime:

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 points back to this repository rather than copying curated files:

• ~/.pi/agent/extensions/plan-mode → extensions/plan-mode/
• ~/.pi/agent/extensions/questionnaire.ts → extensions/questionnaire.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
• ~/.pi/agent/APPEND_SYSTEM.md → system-instruction/APPEND_SYSTEM.md
• ~/.pi/agent/settings.json registers extensions/mcp-extension/ as a local-path package
• ~/.pi/agent/mcp.json registers mcp-servers/camoufox/bin/camoufox-mcp as a stdio MCP server
• the user pi command resolves to build/pi-agent/runtime/bin/pi

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, lockfile, dependencies, and checks, and upstream Pi retains its own build and release process. 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.renocrypt.com/pi-arcweld
• Repository: github.com/appautomaton/pi-arcweld
• Upstream Pi: pi.dev · github.com/earendil-works/pi
• Maintainer: App Automaton · appautomaton.renocrypt.com

---

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