GitHub - topce/pizx: zx + pi

# Step 1: Install Pi CLI (one-time) — needed for AI credentials
# See https://github.com/earendil-works/pi
npm install -g @earendil-works/pi
pi auth login

# Step 2: Install pizx in your project
npm install @topce/pizx

#!/usr/bin/env pizx

// Simple AI query
const answer = await π`what is the capital of France?`
echo(answer)

// Agent patterns
const files = await $`ls src/`
const summary = await π`summarize these files in one sentence: ${files}`
console.log(summary)

chmod +x hello.mjs
./hello.mjs

# Or:
pizx hello.mjs

#!/usr/bin/env pizx

const name = await question('What is your name? ')
const intro = await π`write a friendly greeting for ${name}`
echo(intro)

import { $, π, Π, Ρ, Φ, Σ } from '@topce/pizx'

// Greek letters work everywhere...
const output = await $`ls src/ | grep '.ts'`
console.log(output.stdout)

const review = await π`review this code for issues:\n${output.stdout}`
console.log(review.text)

// ...and so do English word aliases:
import { pi, Pi, ralph, fleet, subagent } from '@topce/pizx'

const answer = await pi`explain async/await`
await Pi`fix the TypeScript errors in src/`
await fleet`review all files in src/`

import '@topce/pizx/globals'

// All Greek tags are available without imports:
const answer = await π`explain async/await`
await Π`fix the lint issues`
await Φ`review all files`

// English aliases too:
const docs = await fleet`check all .ts files`
const plan = await orchestrator`design the architecture`

// Helpers:
configurePi({ model: 'anthropic/claude-sonnet-4-5' })
closeAgent()

pizx -p "explain async/await in JavaScript"
pizx -p --model deepseek/deepseek-chat "summarize this code: @file.ts"
pizx --version

import { γ, goal } from '@topce/pizx'

const result = await γ({
  verifierModel: 'deepseek/deepseek-v4-pro',   // writes contract + verifies
  workerModel: 'deepseek/deepseek-v4-flash',  // does the work
  maxIterations: 5,
  antiSpin: true,        // detect no-progress and flip-flop
  streakMode: 3,         // require 3 consecutive ALL_PASS
  budgetCapUsd: 5.00,    // don't spend more than $5
})`add error handling to the Fleet pattern`

console.log(result.passed)          // true if contract satisfied
console.log(result.contract)        // the formal contract text
console.log(result.terminationReason)  // why it stopped, if early

const result = await Ρ({
  antiSpin: true,       // stop if reviews are >80% identical (no-progress)
  streakMode: 2,        // require 2 consecutive DONE before accepting
  budgetCapUsd: 3.00,   // stop if real cost exceeds $3
})`review and fix issues in src/`

if (result.terminationReason) {
  console.log(`Stopped: ${result.terminationReason}`)  // e.g. "no-progress detected"
}

await Ω({
  plannerModel: 'deepseek/deepseek-v4-pro',  // planning + synthesis
  workerModel: 'deepseek/deepseek-v4-flash',  // worker execution
})`design a notification system`

await Ω({ system: 'You are a senior security architect.' })`design an auth system`
// → "You are a senior security architect.\n\n[PLANNER_SYSTEM]"

const result = await Ω({ qualityCheck: true })`design the system architecture`

if (result.qualityReview) {
  console.log(`Quality score: ${result.qualityReview.score}`)   // 0.0 – 1.0
  console.log(result.qualityReview.assessment)                   // 1-2 sentence assessment
  console.log(result.qualityReview.recommendation)               // improvement suggestion
}

// auto — no gates, runs to completion (default)
await Ω({ confirm: false })`design the system`
await Ω({ confirm: { auto: true } })`design the system`

// semi — gates at major decision points (backward-compatible with confirm: true)
await Ω({ confirm: true })`design the system`
await Ω({ confirm: { semi: true } })`design the system`
// → "── Confirm (dispatch) ──"
// → "Execute 3 sub-task(s) as planned?"
// → "  1. Analyze requirements"
// → "  2. Design architecture"
// → "  3. Document decisions"
// → "Proceed? [Y/n] "

// hitl — gates before EVERY phase, human approves each step
await Ω({ confirm: { hitl: true } })`design the system`
// → pause at plan, dispatch, AND synthesize

await Ρ({ maxIterations: 3 })`refactor the auth module`        // limit improvement cycles
await Ρ({ useTools: false })`analyze the design`                // text-only mode (no file tools)
await Ρ({ maxAgentTurns: 15 })`implement the feature`           // agent turns per execution phase

// Fleet workers can read files
await fleet({ mode: 'agent' })`read package.json and analyze the project`

// Pipeline stages can edit code
await pipeline({ mode: 'agent' })`read src/ and refactor the error handling`

// Orchestrator workers can run commands
await orchestrator({ mode: 'agent' })`check the test coverage and report gaps`

// Debate perspectives can research the codebase
await debate({ mode: 'agent' })`read the architecture docs and debate the design`

await π({ model: 'anthropic/claude-sonnet-4-5' })`explain this algorithm`
await Π.quiet`fix the lint issues in src/`
await Φ({ concurrency: 5 })`review all .ts files`
await Σ.quiet`analyze security across the codebase`
await Θ({ agents: 4, turns: 3 })`debate the architecture`
await Γ({ graph: { nodes: [...], edges: [...] } })`execute workflow`

await π({ thinkingLevel: 'high' })`solve this complex math problem`
await Ω({ thinkingLevel: 'high' })`design the system architecture`

// Per-phase control (patterns only)
await Φ({ plannerModel: '...', workerModel: '...' })`...`

// Per-pattern
await Φ({ timeoutMs: 30000, maxRetries: 2 })`review all .ts files`

// Per-call on π
await π({ timeoutMs: 15000 })`summarize this document`

// Global defaults
configurePi({ timeoutMs: 60000, maxRetries: 3 })

await π({ apiKey: 'sk-...' })`analyze this data`
await Ω({ apiKey: 'sk-...' })`design the system`

await Φ({ concurrency: 10 })`review all files`            // max 10 parallel
await Ω({ workers: 5, concurrency: 3 })`design the system` // 5 tasks, 3 at a time
await Σ({ maxSubTasks: 6, concurrency: 6 })`analyze`       // 6 sub-tasks, all parallel

for await (const chunk of π.stream`tell me a long story`) {
  process.stdout.write(chunk)
}

const result = await Ω`design a notification system`

// Per-call breakdown
for (const t of result.trace) {
  console.log(`Call ${t.call}: ${t.modelId} — ${t.totalTokens} tokens, $${t.cost.toFixed(6)}`)
}

// Aggregates (on both PatternOutput and PiOutput)
console.log(`Total: ${result.totalTokens} tokens`)
console.log(`Cost:  $${result.totalCost.toFixed(4)}`)
console.log(`Calls: ${result.callCount}`)

// Structured phase log — what happened during execution
for (const phase of result.phaseLog) {
  console.log(`${phase.phase}: ${phase.durationMs}ms — ${phase.description}`)
}
// → "plan: 1234ms — Generated plan with 3 workers"
// → "dispatch: 5678ms — Executed 3 worker(s), 3 succeeded"
// → "synthesize: 901ms — Synthesized worker results"

// Works with π too
const answer = await π`explain quantum computing`
console.log(`Input: ${answer.inputTokens}, Output: ${answer.outputTokens}`)
console.log(`Cost:  $${answer.totalCost.toFixed(6)}`)

import { type TagOutput, type WorkerResult } from '@topce/pizx'

function handleResult(result: TagOutput) {
  console.log(result.text)
  console.log(`Took ${result.duration}ms`)
}

await Φ({
  tasks: [
    'analyze the frontend',              // string: standard LLM call
    () => Σ\`analyze the backend\`,       // function: compose a Subagents pattern
    () => Ψ\`review the API design\`,     // function: compose a Critique pattern
  ],
})`review everything`

await Λ({
  stages: [
    'generate product description',       // string: standard LLM call
    (prev) => Ψ\`critique this: ${prev}\`, // function: receives previous output
  ],
})`generate → improve`

import { configurePi, configureAgent } from '@topce/pizx'

configurePi({ model: 'anthropic/claude-sonnet-4-5', maxTokens: 8000, timeoutMs: 60000 })
configureAgent({ maxTurns: 5, excludeTools: ['write'] })

// Agent tools: read, bash, edit, write, grep, ls
await Π({ tools: ['read', 'bash'] })`read-only analysis`          // restrict available tools
await Π({ excludeTools: ['write'] })`review and suggest fixes`     // exclude specific tools
await Π({ cwd: '/path/to/project' })`refactor this module`         // working directory
await Π({ maxTurns: 5 })`quick fix`                                // limit agent turns
await Π({ skills: ['code-simplification'] })`clean up this code`   // load skills
await Π({ system: 'You are a security auditor' })`audit the auth`  // custom system prompt

// Session management
import { closeAgent } from '@topce/pizx'
await closeAgent()  // dispose shared Π session (resets state between scripts/tests)

// π: custom system prompt
await π({ system: 'You are a security auditor' })`review this code`

// π: with appendSystemPrompt
await π({ appendSystemPrompt: 'Respond in JSON format' })`list all .ts files`

// Π: set system prompt and append extra instructions
await Π({ system: 'You are a test engineer', appendSystemPrompt: 'Write tests first' })`add tests for auth`

// Patterns: inject system context via mergeSystem
await Ω({ system: 'Prioritize security over performance' })`design login flow`

// Per-call
await π({ thinkingBudgets: { medium: 16384, high: 65536 } })`analyze`

// Global default
configurePi({ thinkingBudgets: { medium: 20480, high: 131072 } })

// Patterns support it too
await Ω({ thinkingBudgets: { high: 65536 } })`deep analysis task`

import { loadSkillContent, loadSkillContents } from '@topce/pizx'

// Load a single skill
const codeStyle = await loadSkillContent('code-simplification')
if (codeStyle) {
  await π({ system: codeStyle })`refactor auth.ts`
}

// Load multiple skills
const skills = await loadSkillContents(['test-driven-development', 'spec-driven-development'])

// Π accepts skills option — loads and registers skill directories
await Π({ skills: ['code-simplification'] })`clean up this file`

// All patterns accept skills option — injects skills as system context
await Ω({ skills: ['spec-driven-development', 'incremental-implementation'] })`build the feature`
await Φ({ skills: ['test-driven-development'] })`review and add tests`

source ./node_modules/@topce/pizx/src/skill.sh
pizx_use_skill code-simplification "refactor the main module"
pizx_list_skills  # show all available skills

pizx [options] <script>      # Run a pizx script
pizx -p <prompt>              # Quick pi-ai query
pizx --version                # Print version
pizx --help                   # Print help

npm run build                  # Build (JS + DTS)
npm run check                  # Format with Biome
npm run lint                   # Lint (Biome + ESLint)
npm test                       # 363 unit tests (no network)
npm run test:integration       # Integration tests (requires Pi credentials)
npm run test:quality           # Run qualityCheck example
npm run test:confirm           # Run confirm gate example
npm run test:composition-fleet # Run pattern composition in Fleet example
npm run test:composition-pipeline # Run pattern composition in Pipeline example
npm run test:new-features      # Run all 4 feature examples
npm run example:hello          # Run hello example
npm run example:all            # Run all pattern examples