@groeponline/pi-control

A Pi extension that gives humans and coding agents a control plane over the live Pi process — agent sessions, model switching, tool gating, saved runtime state, QA verification, and guardrails — with every change backed by evidence from the same process it controls.

pi-control does not replace Pi's agent runtime, spawn daemons, or mirror state into a second store. It operates directly on Pi's own session tree, model registry, tool inventory, and state history, then verifies what actually happened.

At a glance

• 5 agent tools — pi_session, pi_model, pi_tool, pi_state, pi_verify
• 3 operator commands — /pi-demo, /pi-verify, /pi-qa
• Guardrails — destructive shell and unsafe mutation patterns are denied before execution
• 1 packaged skill — pi-control operating discipline (capture → change → verify → report)
• No telemetry, no daemon, no second runtime — in-process against the live Pi host

Install

Persistent (all Pi sessions):

pi install npm:@groeponline/pi-control

One session only:

pi -e npm:@groeponline/pi-control

Pi loads both the extension and the packaged skill from the package manifest — no extra configuration.

Quick start

Verify a claim about the runtime:

{"tool":"pi_verify","action":"session","expectations":{"entries.gt":5}}

Switch model and thinking level, then confirm:

{"tool":"pi_model","action":"thinking","level":"high"}

{"tool":"pi_verify","action":"model","expectations":{"thinkingLevel":"high"}}

Snapshot state before a risky change, restore it after:

{"tool":"pi_state","action":"save","key":"before-refactor","data":{"phase":"baseline"}}

{"tool":"pi_state","action":"restore","key":"before-refactor"}

Gate the toolset for a bounded run:

{"tool":"pi_tool","action":"set_active","tools":["read","bash"]}

Commands

Command	Purpose
/pi-demo	Demonstrate a concrete Pi workflow or feature with explicit scope, model, and verification commitments.
/pi-verify	Test a claim about Pi runtime behavior and report evidence. A well-evidenced "this does not work" is as valuable as a pass.
/pi-qa	Run a structured QA flow step by step and report PASS/FAIL with evidence.

Agent tools

pi_session — manage sessions

Action	Description
list	List available sessions.
inspect	Show current session details (entry count, branch, model).
fork	Fork from an entry into a new session.
switch	Switch to another session.
compact	Compact the current session.
navigate	Move through the session tree.
label	Set or clear a label on an entry.
rename	Rename the session.

pi_model — control model and thinking

Action	Description
list	List available models.
providers	Show registered providers.
set	Switch the active model.
thinking	Change the thinking level.

pi_tool — gate the active toolset

Action	Description
list	Show all tools and their active/inactive status.
inspect	Show details for a specific tool.
set_active	Replace the complete active tool set.

set_active is a replacement, not a toggle: it defines the full set of active tools. Inspect first, then set the smallest set you need.

pi_state — snapshot, diff, restore

Action	Description
save	Save a named snapshot of runtime state (label, summary, data).
restore	Restore a saved snapshot.
diff	Compare two state snapshots.
history	Show the change history.

pi_verify — assert runtime expectations

Action	Description
session	Assert session properties (entry counts, model, settings).
model	Assert the active model and thinking level.
tool	Assert tool output matched expectations.
state	Assert state snapshot properties.

Guardrails

Lifecycle and tool-call hooks deny unsafe control patterns before execution, including:

• destructive filesystem operations (rm -rf /, rm -rf ~, mkfs, dd if=)
• fork-bomb patterns and remote-to-shell piping (curl … | sh, wget … | sh)
• unsafe session mutations, gated behind explicit confirmation hooks

The operating rule the skill enforces: inspect first, make the smallest change, then verify.

The operating loop

capture (pi_session inspect / pi_state save)
  → change (fork / switch / set / thinking / set_active)
    → verify (pi_verify)
      → report (evidence from the same Pi process)

Every state-changing action is deliberate: switching models, replacing tools, restoring state, or moving between sessions affects the current Pi process. The packaged pi-control skill documents this discipline for agents.

Where it fits

pi-control owns runtime control and verification. The wider GroepOnline Pi suite:

Package	Role
@groeponline/pi-wishcraft	Operator cockpit: powerline status bar, session queue, Skill Studio, ideas inbox
@groeponline/pi-missions	Durable missions that survive context resets
@groeponline/pi-agent-control-extension	Browser/terminal capture, QA evidence recipes, showcase rendering
@groeponline/pi-tools	Shared Pi tooling

The flow: idea (pi-wishcraft) → durable mission (pi-missions) → execution → runtime & evidence verification (pi-control / pi-agent-control-extension).

Package layout

extensions/pi-control/
  index.ts        extension entrypoint — registers commands, tools, guardrails
  tools.ts        the five structured agent tools
  guardrails.ts   lifecycle and tool-call safety hooks
  commands/       /pi-demo, /pi-verify, /pi-qa
skills/pi-control/
  SKILL.md        packaged operating guidance

Development

# package contract (manifest, resources, Pi peer rules, tarball contents)
npm run verify:package

# extension unit tests
npm ci --prefix extensions/pi-control
npm test --prefix extensions/pi-control

The verify:pi-package gate validates the npm/Pi package contract end to end: manifest, declared resources, public metadata, gallery preview format, Pi core peer-dependency rules, and the final packed tarball. CI runs it on every PR and before every publish.

Privacy and telemetry

pi-control collects no telemetry and sends nothing to external services. It operates on the local Pi process; all state and evidence stays under the operator's control.

FAQ

Does it change how Pi works by default? No. It adds commands, tools, and guardrails on top of the standard runtime. Anything that mutates state happens only when a tool call or command asks for it.

Can I use the tools without the commands? Yes. The commands are operator workflows on top of the same five tools; agents can call the tools directly.

Does it work with any model? pi_model operates on whatever models and providers your Pi installation has registered. It switches and verifies; it does not bundle providers.

Where does state live? In Pi's own runtime state, managed through pi_state snapshots. There is no external database or sidecar.

Links

• Pi catalog: https://pi.dev/packages/@groeponline/pi-control
• npm: https://www.npmjs.com/package/@groeponline/pi-control
• Source: https://github.com/GroepOnline/pi-control
• Issues: https://github.com/GroepOnline/pi-control/issues
• Architecture: ARCHITECTURE.md · Changelog: CHANGELOG.md

License

MIT © GroepOnline