{"id":50800676,"url":"https://github.com/topce/pizx","last_synced_at":"2026-06-12T19:04:11.271Z","repository":{"id":363307351,"uuid":"1262737409","full_name":"topce/pizx","owner":"topce","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-08T09:40:23.000Z","size":149,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T11:24:15.046Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/topce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T09:18:01.000Z","updated_at":"2026-06-08T09:40:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/topce/pizx","commit_stats":null,"previous_names":["topce/pizx"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/topce/pizx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fpizx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fpizx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fpizx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fpizx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/topce","download_url":"https://codeload.github.com/topce/pizx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topce%2Fpizx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34258376,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T19:04:08.333Z","updated_at":"2026-06-12T19:04:11.258Z","avatar_url":"https://github.com/topce.png","language":"TypeScript","funding_links":["https://github.com/sponsors/topce"],"categories":[],"sub_categories":[],"readme":"# pizx\n\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/topce?style=social\u0026logo=github)](https://github.com/sponsors/topce)\n\n![pizx — zx fork with native Pi AI integration](github-social-banner.png)\n\n\u003e **zx fork with native Pi AI integration** — 15 template tags for shell scripting, AI text generation, coding agents, agentic patterns, communication, and orchestration topologies.\n\n## Quick Start\n\n```bash\nnpm install @topce/pizx\npi auth login        # one-time: configure Pi AI credentials\n```\n\nWrite a script (`hello.mjs`):\n\n```js\n#!/usr/bin/env pizx\n\n// Simple AI query\nconst answer = await π`what is the capital of France?`\necho(answer)\n\n// Agent patterns\nconst files = await $`ls src/`\nconst summary = await π`summarize these files in one sentence: ${files}`\nconsole.log(summary)\n```\n\nRun it:\n\n```bash\nchmod +x hello.mjs\n./hello.mjs\n\n# Or:\npizx hello.mjs\n```\n\n**New to pizx?** Start with the [Onboarding Guide](docs/onboarding.md).\n\n## Install\n\n```bash\nnpm install @topce/pizx\n```\n\n**Prerequisites:**\n- Node.js \u003e= 22.19.0\n- [Pi AI](https://github.com/earendil-works/pi) installed and configured (`pi auth login`)\n- Shell commands from [zx](https://github.com/google/zx) (`$`, `cd`, `echo`, `fetch`, etc.)\n\n## Writing Scripts\n\n### Shebang\n\n```js\n#!/usr/bin/env pizx\n\nconst name = await question('What is your name? ')\nconst intro = await π`write a friendly greeting for ${name}`\necho(intro)\n```\n\n### Programmatic Import\n\n```js\nimport { $, π, Π, Ρ, Φ, Σ } from '@topce/pizx'\n\nconst output = await $`ls src/ | grep '.ts'`\nconsole.log(output.stdout)\n\nconst review = await π`review this code for issues:\\n${output.stdout}`\nconsole.log(review.text)\n\n// Use the coding agent to fix issues\nawait Π`fix the TypeScript errors in src/`\n```\n\n### CLI Quick Queries\n\n```bash\npizx -p \"explain async/await in JavaScript\"\npizx -p --model deepseek/deepseek-chat \"summarize this code: @file.ts\"\npizx --version\n```\n\n## Tags Reference\n\nEach tag has detailed documentation in [`docs/`](docs/):\n\n### Core\n\n| Tag | Name | Description | Docs |\n|---|---|---|---|\n| `$` | Shell | Shell commands (unchanged from zx) | — |\n| `π` | Pi | AI text generation via pi-ai | [docs/pi.md](docs/pi.md) |\n| `Π` | Capital Pi | Pi coding agent with tools (read, bash, edit, write) | [docs/capital-pi.md](docs/capital-pi.md) |\n\n### Agent Patterns (Ρ Φ Σ Δ Λ Ψ Ω Ν)\n\n| Tag | Name | Flow | Docs |\n|---|---|---|---|\n| `Ρ` | Ralph Loop | analyze → plan → execute → review ↺ | [docs/ralph.md](docs/ralph.md) |\n| `Φ` | Fleet | A, B, C in parallel → aggregate | [docs/fleet.md](docs/fleet.md) |\n| `Σ` | Subagents | decompose → sub-agents → synthesize | [docs/subagent.md](docs/subagent.md) |\n| `Δ` | Debate | perspectives → converge | [docs/debate.md](docs/debate.md) |\n| `Λ` | Pipeline | stage₁ → stage₂ → stage₃ | [docs/pipeline.md](docs/pipeline.md) |\n| `Ψ` | Critique | generate → critique → improve | [docs/critique.md](docs/critique.md) |\n| `Ω` | Orchestrator | plan → dispatch → synthesize | [docs/orchestrator.md](docs/orchestrator.md) |\n| `Ν` | Nu | analyze → negotiate roles → execute → synthesize | [docs/nu.md](docs/nu.md) |\n\n### Communication Patterns (Θ Μ Β)\n\n| Tag | Name | Pattern | Docs |\n|---|---|---|---|\n| `Θ` | Thread | Multi-agent conversation | [docs/thread.md](docs/thread.md) |\n| `Μ` | Memory | Shared blackboard | [docs/memory.md](docs/memory.md) |\n| `Β` | Broadcast | One-to-many messaging | [docs/broadcast.md](docs/broadcast.md) |\n\n### Orchestration Topologies (Α Γ Χ Τ)\n\n| Tag | Name | Pattern | Docs |\n|---|---|---|---|\n| `Α` | Adaptive | Self-adjusting workflow | [docs/adaptive.md](docs/adaptive.md) |\n| `Γ` | Graph | DAG-based execution | [docs/graph.md](docs/graph.md) |\n| `Χ` | Chi | Analyze traces → extract patterns | [docs/chi.md](docs/chi.md) |\n| `Τ` | Tau | Define schema → write → refine → consolidate | [docs/tau.md](docs/tau.md) |\n\n## Architecture\n\nSee [docs/decisions/](docs/decisions/) for Architecture Decision Records covering the key design choices:\n\n- [ADR-001: Template-Tag DSL](docs/decisions/ADR-001-template-tag-dsl.md) — Why patterns are template tags with curried option chaining\n- [ADR-002: Shared Tag Factory](docs/decisions/ADR-002-shared-tag-factory.md) — How `createPatternTag` eliminates 450 lines of boilerplate\n- [ADR-003: Quality Validation](docs/decisions/ADR-003-quality-validation.md) — The `qualityCheck` design and `runQualityReview` helper\n- [ADR-004: Phase Logging](docs/decisions/ADR-004-phase-logging.md) — Structured audit trails via `phaseLog` on every output\n- [ADR-005: Pattern Composition](docs/decisions/ADR-005-pattern-composition.md) — How `TaskDescriptor` enables nested patterns\n- [ADR-006: Confirm Gates](docs/decisions/ADR-006-confirm-gates.md) — Human-in-the-loop approval via `confirm` option\n- [ADR-007: System Propagation](docs/decisions/ADR-007-system-propagation.md) — How `mergeSystem` propagates user prompts\n\n## Advanced Features\n\n### Per-Phase Model Selection\n\nAll patterns support `plannerModel` and `workerModel` for routing high-level reasoning vs execution to different models:\n\n```js\nawait Ω({\n  plannerModel: 'deepseek/deepseek-v4-pro',  // planning + synthesis\n  workerModel: 'deepseek/deepseek-v4-flash',  // worker execution\n})`design a notification system`\n```\n\nWithout per-phase models, patterns fall back to `model` → Pi default.\n\n### System Prompt Propagation\n\nAll patterns respect the `system` option. When you provide a custom system prompt, it is prepended to the pattern's default system prompt — your context is never silently discarded:\n\n```js\nawait Ω({ system: 'You are a senior security architect.' })`design an auth system`\n// → \"You are a senior security architect.\\n\\n[PLANNER_SYSTEM]\"\n```\n\n### Quality Validation\n\nAll 15 patterns support an optional `qualityCheck` flag. When enabled, the pattern runs a post-execution LLM review that scores the final output (0.0–1.0), provides an assessment, and recommends improvements:\n\n```js\nconst result = await Ω({ qualityCheck: true })`design the system architecture`\n\nif (result.qualityReview) {\n  console.log(`Quality score: ${result.qualityReview.score}`)   // 0.0 – 1.0\n  console.log(result.qualityReview.assessment)                   // 1-2 sentence assessment\n  console.log(result.qualityReview.recommendation)               // improvement suggestion\n}\n```\n\n### Human-in-the-Loop (Confirm Gates)\n\nSet `confirm: true` to pause before the main execution phase and ask for approval. The pattern displays a summary of what it's about to do and waits for `[Y/n]` on stdin:\n\n```js\nawait Ω({ confirm: true })`design the system`\n// → \"── Confirm ──\"\n// → \"Execute 3 sub-task(s) as planned?\"\n// → \"  1. Analyze requirements\"\n// → \"  2. Design architecture\"\n// → \"  3. Document decisions\"\n// → \"Proceed? [Y/n] \"\n```\n\nSupported by: `Ω`, `Σ`, `Φ`, `Λ` (more patterns coming).\n\n### Option Chaining \u0026 Quiet Mode\n\nAll tags support option chaining and `.quiet` mode to suppress output:\n\n```js\nawait π({ model: 'anthropic/claude-sonnet-4-5' })`explain this algorithm`\nawait Π.quiet`fix the lint issues in src/`\nawait Φ({ concurrency: 5 })`review all .ts files`\nawait Σ.quiet`analyze security across the codebase`\nawait Θ({ agents: 4, turns: 3 })`debate the architecture`\nawait Γ({ graph: { nodes: [...], edges: [...] } })`execute workflow`\n```\n\n### Timeout \u0026 Retry\n\nAll tags accept `timeoutMs` and `maxRetries` to control LLM call resilience. When unset, the provider SDK defaults apply (typically 10 min timeout, 2 retries).\n\n```js\n// Per-pattern\nawait Φ({ timeoutMs: 30000, maxRetries: 2 })`review all .ts files`\n\n// Per-call on π\nawait π({ timeoutMs: 15000 })`summarize this document`\n\n// Global defaults\nconfigurePi({ timeoutMs: 60000, maxRetries: 3 })\n```\n\n### Token, Cost \u0026 Phase Tracking\n\nEvery pattern output and π call includes an execution trace with token usage, cost, and a structured phase log. All collected automatically — no extra flags needed.\n\n```js\nconst result = await Ω`design a notification system`\n\n// Per-call breakdown\nfor (const t of result.trace) {\n  console.log(`Call ${t.call}: ${t.modelId} — ${t.totalTokens} tokens, $${t.cost.toFixed(6)}`)\n}\n\n// Aggregates (on both PatternOutput and PiOutput)\nconsole.log(`Total: ${result.totalTokens} tokens`)\nconsole.log(`Cost:  $${result.totalCost.toFixed(4)}`)\nconsole.log(`Calls: ${result.callCount}`)\n\n// Structured phase log — what happened during execution\nfor (const phase of result.phaseLog) {\n  console.log(`${phase.phase}: ${phase.durationMs}ms — ${phase.description}`)\n}\n// → \"plan: 1234ms — Generated plan with 3 workers\"\n// → \"dispatch: 5678ms — Executed 3 worker(s), 3 succeeded\"\n// → \"synthesize: 901ms — Synthesized worker results\"\n\n// Works with π too\nconst answer = await π`explain quantum computing`\nconsole.log(`Input: ${answer.inputTokens}, Output: ${answer.outputTokens}`)\nconsole.log(`Cost:  $${answer.totalCost.toFixed(6)}`)\n```\n\nEach `CallTrace` entry includes: call index, model id, prompt/output previews, input/output/cache tokens, cost (USD), and duration.\n\n### Pattern Composition (Nesting)\n\nFleet and Pipeline accept `TaskDescriptor` — either a plain string (for a standard LLM call) or a function that invokes another pattern as a sub-task. See [docs/advanced-features.md](docs/advanced-features.md#pattern-composition-taskdescriptor) for details.\n\n**Fleet with mixed tasks:**\n\n```js\nawait Φ({\n  tasks: [\n    'analyze the frontend',              // string: standard LLM call\n    () =\u003e Σ\\`analyze the backend\\`,       // function: compose a Subagents pattern\n    () =\u003e Ψ\\`review the API design\\`,     // function: compose a Critique pattern\n  ],\n})`review everything`\n```\n\n**Pipeline with composed stages:**\n\n```js\nawait Λ({\n  stages: [\n    'generate product description',       // string: standard LLM call\n    (prev) =\u003e Ψ\\`critique this: ${prev}\\`, // function: receives previous output\n  ],\n})`generate → improve`\n```\n\n### Global Configuration\n\n```js\nimport { configurePi, configureAgent } from '@topce/pizx'\n\nconfigurePi({ model: 'anthropic/claude-sonnet-4-5', maxTokens: 8000, timeoutMs: 60000 })\nconfigureAgent({ maxTurns: 5, excludeTools: ['write'] })\n```\n\n### System Prompt Overrides\n\nAll tags accept `system` (replaces default) and `appendSystemPrompt` (appended after system).\n\n```js\n// π: custom system prompt\nawait π({ system: 'You are a security auditor' })`review this code`\n\n// Π: set system prompt and append extra instructions\nawait Π({ system: 'You are a test engineer', appendSystemPrompt: 'Write tests first' })`add tests for auth`\n\n// Patterns: inject system context via mergeSystem\nawait Ω({ system: 'Prioritize security over performance' })`design login flow`\n```\n\n### Thinking Budgets\n\nFine-grained token budgets per reasoning level. Passes through to providers via `thinkingBudgets`.\n\n```js\n// Per-call\nawait π({ thinkingBudgets: { medium: 16384, high: 65536 } })`analyze`\n\n// Global default\nconfigurePi({ thinkingBudgets: { medium: 20480, high: 131072 } })\n\n// Patterns support it too\nawait Ω({ thinkingBudgets: { high: 65536 } })`deep analysis task`\n```\n\n### Skill Integration\n\nLoad Pi agent skills from disk and inject them as system context. Skills are discovered from the same paths as `skill.sh`: `.pi/skills`, `.agents/skills`, `~/.pi/agent/skills`, etc.\n\n```js\nimport { loadSkillContent, loadSkillContents } from '@topce/pizx'\n\n// Load a single skill\nconst codeStyle = await loadSkillContent('code-simplification')\nif (codeStyle) {\n  await π({ system: codeStyle })`refactor auth.ts`\n}\n\n// Load multiple skills\nconst skills = await loadSkillContents(['test-driven-development', 'spec-driven-development'])\n\n// Π and all patterns accept skills option\nawait Π({ skills: ['code-simplification'] })`clean up this file`\nawait Ω({ skills: ['spec-driven-development', 'incremental-implementation'] })`build the feature`\n```\n\n## CLI Reference\n\n```bash\npizx [options] \u003cscript\u003e      # Run a pizx script\npizx -p \u003cprompt\u003e              # Quick pi-ai query\npizx --version                # Print version\npizx --help                   # Print help\n```\n\n**Options:**\n- `-p, --prompt \u003ctext\u003e` — Run a quick pi-ai query (no script needed)\n- `-m, --model \u003cid\u003e` — Specify AI model to use\n- `--quiet` — Suppress output except errors\n- `--shell \u003cpath\u003e` — Shell to use (default: auto-detect)\n\n## Commands\n\n```bash\nnpm run build                  # Build (JS + DTS)\nnpm run check                  # Lint and format with Biome\nnpm test                       # 223 unit tests (no network)\nnpm run test:integration       # Integration tests (requires Pi credentials)\nnpm run test:quality           # Run qualityCheck example\nnpm run test:confirm           # Run confirm gate example\nnpm run test:composition-fleet # Run pattern composition in Fleet example\nnpm run test:composition-pipeline # Run pattern composition in Pipeline example\nnpm run test:new-features      # Run all 4 feature examples\nnpm run example:hello          # Run hello example\nnpm run example:all            # Run all pattern examples\n```\n\n## Examples\n\nSee [`examples/`](examples/) for runnable examples of every pattern and feature:\n\n### Pattern Examples\n\n- [`hello-pizx.mjs`](examples/hello-pizx.mjs) — Basic script with shell + AI\n- [`basic-pi.mjs`](examples/basic-pi.mjs) — π text generation\n- [`basic-capital-pi.mjs`](examples/basic-capital-pi.mjs) — Π coding agent\n- [`pattern-ralph.mjs`](examples/pattern-ralph.mjs) — Ralph Loop\n- [`pattern-fleet.mjs`](examples/pattern-fleet.mjs) — Fleet parallel execution\n- [`pattern-debate.mjs`](examples/pattern-debate.mjs) — Multi-perspective debate\n- ... and more for every pattern\n\n### New Feature Demos\n\n- [`test-quality.mjs`](examples/test-quality.mjs) — `qualityCheck` + `system` + `phaseLog`\n- [`test-confirm.mjs`](examples/test-confirm.mjs) — Human-in-the-loop approval gate\n- [`test-composition-fleet.mjs`](examples/test-composition-fleet.mjs) — Pattern composition in Fleet\n- [`test-composition-pipeline.mjs`](examples/test-composition-pipeline.mjs) — Pattern composition in Pipeline\n\n## License\n\nMIT\n\n## Credits\n\nBuilt on the shoulders of two outstanding tools:\n\n- [**zx**](https://github.com/google/zx) by [Anton Medvedev](https://github.com/antonmedv) — the original shell scripting tool for Node.js that popularized template-tag ergonomics for command execution. pizx preserves every zx API (`$`, `cd`, `echo`, `fetch`, `chalk`, etc.) unchanged.\n- [**Pi**](https://github.com/earendil-works/pi) by Mario Zechner / Earendil Works — the unified LLM API and coding agent harness that powers all `π`, `Π`, and pattern tags through `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopce%2Fpizx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftopce%2Fpizx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopce%2Fpizx/lists"}