swarm-pi-code-plugin

繁體中文

swarm-pi-code-plugin connects Claude Code and Codex to a bounded Pi coding worker for repository-grounded analysis, planning, review, and implementation. It is designed for teams that want a second coding-agent perspective without giving that worker unrestricted shell access or ownership of Git delivery.

The host remains in control of intent, approvals, verification, commits, and pushes. Pi receives only the tools and worktree that the current task allows.

Architecture

flowchart LR
    H[Claude Code or Codex] --> A[Host adapter]
    A --> R[Shared Pi runner]
    R --> P[Embedded Pi session]
    P --> Q[Durable Host Assistance]
    Q --> A
    R --> D[Discovery parent]
    D --> E[Isolated experiment child]
    R --> C[Confirmed host-broker child]
    P --> W[Assigned Git worktree]
    R --> S[Shared state and job artifacts]
    H --> V[Host-owned review and verification]
    W --> V

Claude Code and Codex are host surfaces, not worker engines. Both invoke the same runner and share model configuration, project profile, job history, and worktree-aware state.

Delegated tasks resolve to role-specific model chains and thinking levels. Implementation jobs add scoped mutation tools, require a clean assigned worktree, and receive a fresh read-only semantic verifier. Strict exposes no shell, Adaptive authorizes bounded shell and network actions through policy and durable approval, and Lenient retains broad outbound access inside the OS sandbox. Git delivery remains host-owned.

Runtime configuration and jobs stay outside the checked-out worktree. Git repositories use .git/swarm-pi-code-plugin/ through the common Git directory; non-Git folders use an OS user-state namespace. Credentials stay in Pi's user credential store. Browser input becomes an opaque, session-local draft and never enters project artifacts or localStorage.

See the architecture reference and configuration reference for implementation details. See Host Assistance and Discovery for the live worker-to-host context loop, schema-gated experiment micro-SDLC, Advisor boundaries, discover-to-plan handoff, and isolated Host Actions 0.5.

Install

Requirements

• Node.js 22.19.0 or newer for installed plugins.
• A supported Claude Code or Codex installation.
• A Git repository for worktree-aware implementation jobs.
• macOS, or Linux with bubblewrap, socat, and ripgrep, to enable lenient sandbox mode.

Claude Code

Add the GitHub repository as a marketplace and install the plugin:

claude plugin marketplace add https://github.com/JiaWeiXie/swarm-pi-code-plugin
claude plugin install swarm-pi-code-plugin@swarm-pi-code-plugin

Restart Claude Code or run /reload. For local development:

claude --plugin-dir /absolute/path/to/swarm-pi-code-plugin/plugins/swarm-pi-code-plugin

Codex

This repository contains a local marketplace:

codex plugin marketplace add /absolute/path/to/swarm-pi-code-plugin
codex plugin add swarm-pi-code-plugin@swarm-pi-code-plugin-local

Start a new Codex task so skills are reloaded. The available skills are:

$swarm-pi-configure
$swarm-pi-project
$swarm-pi-ask
$swarm-pi-review
$swarm-pi-plan
$swarm-pi-implement
$swarm-pi-orchestrate
$swarm-pi-discover
$swarm-pi-scaffold
$swarm-pi-setup

Usage

Choose the right workflow

Situation	Claude Code	Codex
First provider, model, and project setup	/swarm-pi-code-plugin:swarm-pi-configure	$swarm-pi-configure
Change Provider or model priority	/swarm-pi-code-plugin:swarm-pi-configure --reconfigure	$swarm-pi-configure
Repeatedly change project goal, folders, or task types	/swarm-pi-code-plugin:swarm-pi-project	$swarm-pi-project
Ask a repository question or request analysis	/swarm-pi-code-plugin:swarm-pi-ask	$swarm-pi-ask
Create a read-only implementation plan	/swarm-pi-code-plugin:swarm-pi-plan	$swarm-pi-plan
Review working-tree or branch changes	/swarm-pi-code-plugin:swarm-pi-review	$swarm-pi-review
Make an explicit scoped code change	/swarm-pi-code-plugin:swarm-pi-implement	$swarm-pi-implement
Run multiple read-only perspectives	/swarm-pi-code-plugin:swarm-pi-orchestrate	$swarm-pi-orchestrate
Investigate unknown requirements with gated evidence and experiments	/swarm-pi-code-plugin:swarm-pi-discover	$swarm-pi-discover
Design and create a new project	/swarm-pi-code-plugin:swarm-pi-scaffold	$swarm-pi-scaffold
Configure project-local development tools	/swarm-pi-code-plugin:swarm-pi-setup	$swarm-pi-setup

Claude Code commands and Codex skills use the same runner protocol: they check readiness and pending notifications first, preserve original requests across configuration, default to supervised execution, and require explicit user decisions for approvals, adoption, artifact materialization, and delivery.

First setup

Run the host-specific setup entry point. The browser walks through six steps:

1. Connect cloud, subscription, ambient-identity, or local AI services with provider-specific fields.
2. Choose a project primary model and ordered fallbacks.
3. Assign model chains and thinking levels to worker roles.
4. Choose sandbox, classifier, approval, background, Decision Mode, Host Assistance, Advisor, doctrine metadata, and Host Action policies.
5. Review the detected Git, empty-folder, or adoption workspace state.
6. Test the primary and required classifier models, then save atomically.

If setup was opened by a delegated request, the Host retains that request and resumes it after configuration. Cancellation or idle timeout does not require the user to restate the task. Unsaved browser drafts retain only non-sensitive role, safety, and workspace fields.

Readiness is task-specific. A workspace may be ready for research while mutation or delivery is blocked. In particular, a Git repository without an initial commit reports git-unborn; implementation fails before model startup and returns scaffold or adoption actions plus a resumable continuation.

The connection list is intentionally empty when no usable service is detected. Custom endpoints select their API protocol before model discovery. Provider IDs remain internal, and model limits stay automatic when the endpoint and Pi catalog do not establish them.

Provider connections

The setup form is driven by the pinned Pi provider catalog. OpenAI uses the Responses adapter, Anthropic uses Messages, and mixed providers retain Pi's per-model adapter. Cloud providers show only their required project, region, resource, account, or deployment fields.

ChatGPT Plus/Pro is a separate ChatGPT subscription connection backed by Pi's openai-codex browser or device-code OAuth. It is not loaded through an OpenAI API-key field. GitHub Copilot and Anthropic subscription sign-in use the same bounded OAuth flow.

Custom endpoints choose one protocol: OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages. Model discovery and Verify API are separate actions; loading /models does not prove that generation, tools, or reasoning work. If a server has no model-list endpoint, model IDs can be entered manually without being marked verified.

After a connection is staged, configuration, credential replacement, API verification, sign-out, and project removal remain separate actions. Leaving a secret field blank keeps the saved credential; no existing secret is returned to the browser.

Reconfigure

Provider and model settings can be reopened with --reconfigure or the Codex configure skill. Project settings have a separate repeatable flow:

/swarm-pi-code-plugin:swarm-pi-project
$swarm-pi-project

The project flow reads current role, safety, and profile settings, then updates only state.json. It does not rewrite model configuration, credentials, or job history.

Execution safety and roles

Projects default to Strict, which keeps scoped Pi tools and exposes no Bash. Adaptive adds policy-classified Bash and network access with bounded capability leases and optional supervisor approval. Lenient adds broad outbound access through macOS Seatbelt or Linux Bubblewrap. All shell modes use an isolated environment without model tokens, SSH sockets, or host secrets.

Adaptive classifier prompts expose only the proposed action and limited policy context to the configured provider. Lenient source visible to the worker can be sent to external services. Unsupported platforms and missing dependencies fail closed and never fall back to an unsandboxed shell.

Decision Mode controls bounded orchestration depth: Cost runs one base perspective, Balance two, and Power three. Host Assistance context budget and Advisor quotas are configured separately. Advisor is off by default and adds read-only, non-recursive consultations when enabled. The first-principles-qds-v1 toggle is currently persisted metadata; 0.5.0 does not yet execute an automatic Question/Delete/Simplify convergence pass.

Host Assistance is on by default. It lets a live Pi session ask the Host for a bounded workspace, Web, official documentation, paper, connector, installed skill, or human-decision result. The Host chooses the actual capability and returns one typed, cited, correlated [UNTRUSTED_HOST_CONTEXT] bundle. Secret egress is denied; connectors and non-public egress can require approval.

Role routing keeps each responsibility's primary model, Thinking level, retry limit, and supported execution modes visible. Adaptive mode separately selects the classifier chain and approval fallback inside the sandbox capability ceiling.

Workspace and review

Workspace setup records the product goal, allowed folder scope, and delegated task kinds after reporting Git readiness. Review then shows the effective provider protocol, authentication source, model source, verification state, role routing, and safety policy before the transaction is committed.

Successful save replaces credentials and configuration transactionally, clears the in-memory drafts, and closes the temporary local server. Any published setup example must use an isolated demo workspace and contain no real credentials.

Enforced project policy

Configured allowed task kinds are an admission gate: a disallowed kind is rejected before the job runs, rather than being a prompt suggestion. Configured allowed folders constrain the scoped filesystem tools, and implementation writes are enforced at three layers: the tool boundary, the sandbox write allowlist in adaptive and lenient Bash modes, and a postflight changed-path check. Omitting these restrictions preserves whole-workspace behavior for backward compatibility. Reads and writes differ: while the scoped Pi filesystem tools enforce read scope and the three layers above enforce implementation writes, raw Bash reads in adaptive and lenient modes are not folder-scoped and can read within the workspace subject to the sensitive deny paths; use Strict mode when folder-level read confidentiality is required. See Enforced Project Policy for the technical contract.

Non-interactive runner

The shared runner is useful for automation and host integration:

mise exec -- node scripts/pi-runner.mjs models --json
mise exec -- node scripts/pi-runner.mjs providers --json
mise exec -- node scripts/pi-runner.mjs configure --host codex --section project --no-open
mise exec -- node scripts/pi-runner.mjs init --json
mise exec -- node scripts/pi-runner.mjs status --json
mise exec -- node scripts/pi-runner.mjs doctor --smoke-test --json
mise exec -- node scripts/pi-runner.mjs ask --host codex --prompt-file /path/to/question.md --json
mise exec -- node scripts/pi-runner.mjs