piolium: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project at a glance

Piolium is a Pi extension (a plugin for @earendil-works/pi-coding-agent) that ships a multi-phase repository security audit pipeline. It is not a standalone CLI — it's loaded into a pi session, which then exposes the /piolium-* slash commands defined here. The bundled sub-agents (agents/) and skills (skills/) are committed to the repo.

Runtime is Bun ≥1.1.0 (see package.json#engines). All Pi SDK packages are listed as peerDependencies and provided by the host pi process.

Commands

bun install
bun run typecheck   # tsc --noEmit
bun run lint        # biome check .
bun run format      # biome format --write .
bun run test        # vitest run (fileParallelism: false — audit-state tests touch real fs)

# Run a single test file or filter by name
bun run test -- test/scheduler.test.ts
bun run test -- -t "phase status strip"

# Dev install into Pi (edits in this checkout land immediately, no reinstall)
pi install ./
# Or load the extension ad-hoc without touching settings:
pi -e ./extensions/piolium/index.ts

Driving the extension once installed: pi -p "/piolium-balanced --fresh" (one-shot) or start pi and type /piolium-status. End-to-end harness check: /piolium-smoke.

Architecture

Extension surface (extensions/piolium/index.ts)

The default export pioliumExtension(pi) is the single entry point Pi calls per session. It:

1. Registers session flags (--plm-dir, --plm-since, --plm-scan-limit, --plm-scan-since, and the --plm-*-retries/--plm-*-backoff* family). Each flag mirrors to a PIOLIUM_* env var via applyPioliumProcessFlagEnv so downstream modules read a single source of truth (process.env).
2. Registers a piolium-stream message renderer that pretty-prints sub-agent tool-call/result events nested under the originating phase tag.
3. Registers each /piolium-* slash command. Every handler delegates to a mode runner under extensions/piolium/modes/ and wires phase-strip UI through createPhaseStripCommandUi.
4. Registers the bundled anthropic-vertex provider (providers/anthropic-vertex.ts), but only when Vertex looks configured — isAnthropicVertexConfigured() gates it on the PIOLIUM_VERTEX override or any Google/Vertex env var, so a plain install doesn't advertise a provider it can't authenticate. PIOLIUM_VERTEX is read straight from process.env (no --plm-* flag): flag env mirroring runs during command parsing, which is after this init-time registration, so a flag couldn't take effect here.