Skip to content

Coding package

pi-roundtable-coding adds a managed repository shelf and a separate Pi coding worker. The worker can edit and commit a clone, then report its branch and changes. Shipping is separate: repo_push pushes only a previously reported full SHA to the default branch, without force, after the host’s hold gate permits it.

Terminal window
bun add pi-roundtable-coding pi-roundtable

Use Bun 1.4.4 or newer on Linux or macOS, pi-roundtable >=0.50.0 <0.51.0, and Pi >=1.0.0 <2. A host on Pi 0.99.x must update its Pi dependencies before adding this package. Install Git and GitHub CLI (gh) for the default clone implementation. The host also needs a Git credential with repository read access and write access only where required, plus Pi model credentials. The default clone uses gh repo clone; later fetch and push operations need a configured Git credential helper.

import { coding } from "pi-roundtable-coding";
export default {
// ...your roundtable settings...
plugins: [coding({
shelfDir: "/srv/roundtable/repos",
model: "provider/model-id",
})],
};
Option Default Purpose
shelfDir required Directory for managed clones.
model required Worker Pi model as provider/model-id.
thinking medium Worker thinking level.
ownerRepos [] Exact owner/repo names exempt from the plugin’s push hold.
isOwnerRepo none Trusted host push-exemption policy, including future clones; only literal true grants one.
pushHoldText repository, sha, target and branch Trusted wording for the approval card of a held repo_push; it never changes who is held.
adoptClones [] Startup moves of existing standalone clones, preserving contents and never replacing a shelf destination.
resolveRun configured worker, caller channel Per-caller model, thinking, report channel, and optional thread origin.
postChangeReport caller surface Post the change record in the calling identity/channel.
presentation English package text Change-report post/result and task-start wording, including omitted implicit skills.
toolText package wording Trusted description and argument descriptions for each repository tool as { repo_task: { description, parameters: { task: "…" } } }; does not change tool arguments or approval rules.
threads / threadText none / English Progress and approval thread port, with host-owned wording.
workerWorkspace / workerPrompt clone / generic instructions Trusted shell-policy write boundary and standing prompt replacement.
workerBlockText “The owner declined / has not approved this call. Do not retry it or work around it; list it under Held in your report.” Trusted wording of what the worker reads when a call is declined or held; never changes who is held.
limits 20,000 report characters, 10 held entries of 1,000 characters { reportChars?, heldEntries?, heldChars? }: bounds of what a report keeps of a long run; each is a whole number of at least 1, or Infinity.
diagnosticChars 600 Longest git, gh and worker error text kept in a failure; a whole number of at least 1, or Infinity.
skipUnavailableCarriedSkills false Opt in to skipping/disclosing unavailable implicit skills; explicit requests still refuse them.
workerPackages [] Absolute paths to installed Pi extension packages loaded by workers.
agentDir Pi host directory Pi login and model configuration directory.
workerEnv {} { pass? }: more host variables the worker process gets for its model, beyond its models.json $VARs, CLAUDE_* and ANTHROPIC_*; its shell never gets them.
githubToken host GH_TOKEN at setup A string or a function, given as GH_TOKEN to the shelf’s git and gh calls only.
timeoutMs 3600000 Work-time limit; time waiting for owner approval is excluded.
holds none Additional worker hold check.
clone ghClone Alternative Git-host clone implementation.
worker PiCodingWorker Trusted worker runner replacement.
onResult surface reply Custom report delivery.

resolveRun(turn) returns { model, thinking, channel, origin? }; carried skills still follow the caller. onResult receives the loaded skillNames and optional thread in the job, allowing localized queued conversation turns rather than raw surface replies. Configured threads host approval cards and archive before result delivery; a missing thread leaves risky calls held. The clone layout stays shelfDir/owner/repo, with no database migration.

This is a host coding desk, not a sandbox. The worker process gets the shell’s environment whitelist, PI_CODING_AGENT_DIR, the variables its model may read (each $VAR its models.json names, CLAUDE_*, ANTHROPIC_*) and the names in workerEnv.pass; its shell gets only the whitelist and the host’s shellEnv, never the model’s credentials. It can still read files accessible to the host user, run shell commands, use the network, and commit changes. The hold rule detects recognized risky shell actions, but it is a heuristic, not an OS isolation boundary. Run it only with trusted repositories and code, preferably under a dedicated low-privilege host account. Use a container or VM if host access is unacceptable. Keep tokens out of URLs and use least-privilege credentials; the package avoids logging credentials and subprocess diagnostics.

Review worker changes and verification before using repo_change_report and repo_push. ownerRepos and the trusted isOwnerRepo policy bypass only this package’s push hold; they do not bypass shell holds or other host rules. Never derive the policy from model input or repository files. Custom prompts and presentation hooks do not bypass exact-SHA report receipts, non-force pushes, cancellation or process-group cleanup. See the pi-roundtable-coding README for the full workflow, tool contracts, and limits.