pi-arcweld
GitHub

A local workspace for the Pi coding agent

Don't fork it. Weld it.

pi-arcweld joins a curated local layer to pinned upstream Pi along one visible seam: extensions, system guidance, MCP tooling, and a reproducible runtime. Upstream stays upstream. The workspace stays yours.

Assemble the workspace Inspect the source
Member A · upstream

Upstream Pi

pi-mono/ stays a pinned submodule: read and built beside, never rewritten.

Member B · local

The local layer

Extensions, system guidance, and runtime scripts, each at one reviewable address.

Process
Curated local layer
Joint
Upstream ⟂ local
Filler
Five components
Inspection
Fully auditable

Pass 01 · Root

A sound weld starts at the root.

The root pass fuses the boundary and nothing else. Upstream Pi stays pinned in pi-mono/, and every local decision lives at an address you can audit in one pass.

Read the workspace rules
Source
pi-mono/ · pinned to upstream main
Behavior
extensions/ · owns every curated extension
Guidance
system-instruction/APPEND_SYSTEM.md
Runtime
build/pi-agent/ · generated and untracked

Pass 02 · Fill

Five fill passes. No private fork.

Each pass changes how Pi is assembled or extended, and leaves upstream legible, replaceable, and current.

The build helper stages packages, artifacts, and the runnable agent beneath build/pi-agent/. Upstream source is read; generated output lands elsewhere.

Trace the runtime wiring
  • Promotes a smoke-checked runtime artifact.
  • Links the user pi command to the verified build.
  • Keeps package state out of pi-mono/.

Plan state is appended instead of rebuilding Pi's system prompt or tool inventory, preserving the provider cache prefix across mode transitions.

Read the plan-mode contract
  • Restricts built-in write and edit to canonical plan files.
  • Blocks model calls to Pi's built-in Bash while active.
  • Acts as a local mutation guard, not a universal sandbox.

Configured servers are discovered in the background while the model sees a fixed two-tool surface. Connection details and secret values remain outside the prompt.

Inspect the MCP security model
  • User-global configuration is the consent boundary.
  • Catalog snapshots preserve a stable prompt prefix.
  • Server metadata and output are treated as untrusted.

The questionnaire turns vague branches into visible decisions: focused options, multi-question continuity, free-text escape hatches, and explicit cancellation.

Read the extension source
  • Supports single and multiple selection.
  • Preserves context across question sequences.
  • Loads as a curated user-level extension.

A canonical global append file improves response behavior without replacing Pi's generated system prompt, active tool guidance, or discovered project context.

See the instruction model
  • Preserves the runtime-generated prompt head.
  • Avoids project-level files that shadow global guidance.
  • Keeps machine-specific captures local and ignored.

Pass 03 · Cap

From clone to a verified pi.

Clone the pinned source, assemble the runtime outside upstream, and confirm the pi on your PATH is the artifact you just built.

Weld log · local machine 
# clone the workspace and its pinned Pi source
$ git clone --recurse-submodules https://github.com/appautomaton/pi-arcweld.git pi-arcweld
$ cd pi-arcweld

# assemble, link, and verify the external runtime
$ scripts/build-pi-agent.sh --link-user-bin
$ pi --version

# verify repository rules and user-level wiring
$ scripts/check-workspace.sh
$ scripts/check-user-wiring.sh

Final · Inspection

Every weld gets inspected. Every choice stays visible.

That is the whole architecture: preserve the source boundary, give curated behavior one owner, and verify the runtime that reaches your shell.

Open on GitHub