An agentic workflow orchestrator built on pi.dev. Define pipelines as YAML packages, configure workers, schedule them with cron triggers, gate steps behind human approvals, enforce budget caps — and watch runs execute in real-time through the web portal.
┌─────────────────────────────────────────────────────────────┐
│ Web UI (React) │
│ Dashboard │ Pipelines │ Workers │ Approvals │ Run Detail │
└─────────────────┬───────────────────┬───────────────────────┘
│ REST + WebSocket │
┌─────────────────┴───────────────────┴───────────────────────┐
│ Server (Express) │
│ Execution Engine │ Trigger Manager │ Budget Guard │
│ Approval Service │ REST API │ WebSocket │
└────────┬──────────────────────────────┬─────────────────────┘
│ │
┌────────┴────────┐ ┌────────────────┴────────────────────┐
│ PostgreSQL │ │ Pi.dev Execution Layer │
│ (embedded dev) │ │ Sessions │ Skills │ Tools │
└─────────────────┘ └─────────────────────────────────────┘
Monorepo packages:
| Package | Description |
|---|---|
packages/db |
Drizzle ORM schema + migration client |
packages/shared |
Shared API types, status enums, WebSocket message types |
packages/cli |
pawn CLI — manage pipelines, runs, and packages from the terminal |
packages/mcp |
MCP server — exposes pipelines, runs, and skills as MCP tools/resources |
server |
Express API + embedded PostgreSQL + execution engine |
ui |
React + Vite + TailwindCSS operator dashboard |
See docs/ for detailed component documentation.
- Node.js >= 20.6
- pnpm >= 10
- Gemini API key
git clone <repo>
cd pawn
cp .env.example .env
# Add your GEMINI_API_KEY to .env
pnpm install # postinstall auto-configures embedded-postgres
pnpm db:generate # generate SQL migrations from schema
pnpm dev # starts server on :3009 + UI on :3008Open http://localhost:3008. The Daily Absurdist pipeline seeds automatically on first boot.
cp .env.example .env
# Add your GEMINI_API_KEY to .env
docker compose up -dOpen http://localhost:8080. API at http://localhost:3009.
- Go to Pipelines → click Run next to "The Daily Absurdist"
- Enter a topic (e.g.
"AI replacing middle managers") - Click Run Pipeline → redirected to Run Detail
- Watch steps execute in real-time
Install the CLI globally (published to GitHub Packages):
# Configure the @i75corridor scope once (needs read:packages PAT)
export NODE_AUTH_TOKEN=<your-github-pat>
npm config set @i75corridor:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken ${NODE_AUTH_TOKEN}
npm install -g @i75corridor/zh-cliPoint it at your server (default is http://localhost:3009):
pawn config set server http://localhost:3009Trigger a run and stream output:
pawn run "The Daily Absurdist" --input topic="AI hype" --watchScaffold a new pipeline package:
pawn new my-pipelineSee docs/cli.md for the full command reference.
Define multi-step workflows as YAML packages or build them entirely in-app. Each step references a skill, a prompt template, and optional configuration. Steps execute sequentially; outputs are accessible in downstream prompt templates via {{steps.N.output}}.
Create pipelines and skills directly in the UI without touching files. The Agent AI (built-in chat panel) can scaffold skills, write scripts, and wire up pipeline steps — all changes write through to disk in real time. When ready, export as a .tar.gz archive or publish directly to a GitHub repository with one click. See docs/pipeline-packages.md for the full workflow including GitHub auth for publishing.
Skills are folders in SKILLS_DIR with a SKILL.md (system prompt + frontmatter) and an optional scripts/ directory of executable tools. Each skill runs as a pi LLM agent session using the pipeline's configured model. Specialized capabilities like image generation and publishing are provided by external skill packages rather than built into the server.
Schedule pipelines to run automatically. Set a cron expression, timezone, and default inputs — the trigger manager fires the pipeline at the scheduled time.
Mark any pipeline step with approvalRequired: true. The run pauses at that step, an approval request appears in the Approvals page (with a live badge count in the sidebar), and the run resumes only after a human approves. Approvals can include an optional note.
Set monthly spending caps per worker or per pipeline. The budget guard checks the cap before each pi step. If the hard stop threshold is exceeded, the step (and run) fails with a clear error. Cost events are recorded after each step with real token counts.
Pi.dev agent sessions are persisted per (worker, run) pair. Workers can resume their context across steps if needed. Session directories are stored in DATA_DIR/sessions/ and tracked in the worker_sessions table.
All step events stream to the UI over WebSocket as they happen — text deltas, tool calls, status changes. Step cards in Run Detail expand when running and collapse automatically on completion.
| Variable | Required | Default | Description |
|---|---|---|---|
GEMINI_API_KEY |
Yes | — | Google API key (Gemini + Imagen) |
ANTHROPIC_API_KEY |
No | — | Anthropic API key |
OPENAI_API_KEY |
No | — | OpenAI API key |
PORT |
No | 3009 |
HTTP server port |
DATA_DIR |
No | server/.data |
Embedded Postgres data + session storage |
PIPELINES_DIR |
No | ../pipelines |
Pipeline package directory |
SKILLS_DIR |
No | ../skills |
Pi.dev skills directory |
OUTPUT_DIR |
No | ../output |
Generated file output directory |
pnpm dev # start server + UI in parallel
pnpm db:generate # regenerate SQL migrations from schema
pnpm db:reset # wipe embedded postgres data (next dev re-seeds)
pnpm typecheck # typecheck all packages
pnpm --filter @i75corridor/zh-cli build # build the CLI binarypawn/
├── pipelines/ # Pipeline packages (YAML config)
│ └── daily-absurdist/
│ ├── pipeline.yaml # Manifest: model, steps (skill-based), inputSchema
│ └── COMPANY.md # Context file (interpolated into skill prompts)
├── skills/ # Skill definitions (SKILL.md + scripts/)
│ ├── researcher/
│ │ ├── SKILL.md # Frontmatter (name, type) + system prompt body
│ │ └── scripts/
│ │ └── web_search.js # Tool: read JSON from stdin, write result to stdout
│ ├── writer/SKILL.md
│ ├── editor/SKILL.md
│ ├── imagen/SKILL.md
│ └── publisher/SKILL.md
├── packages/
│ ├── db/src/schema/ # Drizzle schema (all tables)
│ └── shared/src/index.ts # Shared API + WS types
├── server/src/
│ ├── index.ts # Bootstrap: Postgres, Express, Engine
│ ├── seed.ts # Config-driven pipeline seeder
│ ├── routes/ # REST API handlers
│ │ ├── workers.ts
│ │ ├── pipelines.ts
│ │ ├── runs.ts
│ │ ├── triggers.ts
│ │ ├── approvals.ts
│ │ └── budgets.ts
│ ├── services/
│ │ ├── execution-engine.ts # Pipeline run orchestration
│ │ ├── pi-executor.ts # Pi.dev session bridge
│ │ ├── builtin-workers.ts # imagen + publish worker types
│ │ ├── trigger-manager.ts # Cron scheduler
│ │ └── budget-guard.ts # Budget checks + cost recording
│ └── ws/index.ts # WebSocket broadcast manager
└── ui/src/
├── pages/ # Dashboard, Pipelines, Approvals, RunDetail
└── lib/ # API client, WebSocket hook
Tracked on the i75Corridor project board.