pi-agora

Agora-style shared memory for independent pi workers on real projects, after Agora: Git as Shared Memory for Collective AutoResearch. Every attempt on a project task — result, failure, or verification — becomes an immutable commit in a Git contribution DAG under .agora/. Workers query that DAG for the frontier and pick the most neglected task. Nothing is lost, and a second worker (or you) can audit every claim later.

See docs/design.md for the module map and the design rationale.

A real recorded session: the task contract (verify.sh), the task pool, init, a headless pi worker passing verification, the frontier, and the contribution DAG as plain git history. Play the original with asciinema play docs/agora-demo.cast.

Install as a pi package

pi install npm:@dastardly_duck/pi-agora

This registers the agora tool (runs the bundled CLI; no pi-agora on PATH needed) and loads the agora skill, so any pi session can drive the DAG: ["frontier", "/proj"], ["run", "/proj", "--model", "provider/model", "--time", "30m"], and so on. Workers still spawn whatever pi is on PATH (--pi to override).

CLI-only install

npm install -g @dastardly_duck/pi-agora

Project layout

<project>/
├── tasks/
│   ├── <name>/
│   │   ├── TASK.md        # what to do (given to the agent verbatim)
│   │   ├── verify.sh      # acceptance check; exit 0 means pass
│   │   └── workspace/     # created on demand; the agent works here
└── .agora/                # git repo; one commit per contribution

Use

pi-agora init ~/code/my-project          # publish task contributions
pi-agora tasks ~/code/my-project         # list tasks
pi-agora frontier ~/code/my-project      # frontier + unverified results
pi-agora run ~/code/my-project \
  --model openrouter/minimax/minimax-m2.5 \
  --pi /path/to/pi                        # work until every task has results

start (free-text goal → GOAL.md → iterate), iterate (generate the next task from the goal when the pool is dry), and serve (read-only HTTP API for the DAG; see openapi.json) follow the same shape — pi-agora --help lists every flag.

run loops: pick the task with the fewest attempts, run headless pi on it in the task directory, run verify.sh, and publish a result (or failure) contribution plus a verification contribution for it. Every run gives each open task up to --max-attempts fresh attempts (default 2); history never blocks new work, and tasks with a passing verification are skipped forever. Run several workers against the same project to work in parallel; contributions are append-only, so workers never destroy each other's record. The diversity rule is a pure function (pickNeglectedTask), so more sophisticated selection can be added without touching the worker.

Local LLMs

pi has no built-in ollama or LM Studio provider. Register one with a custom-provider extension (pi.registerProvider(), see packages/coding-agent/docs/custom-provider.md). Point an OpenAI-compatible provider at http://127.0.0.1:11434/v1 (ollama) or http://127.0.0.1:1234/v1 (LM Studio), then pass the extension's model id:

pi-agora run ~/code/my-project --model ollama/qwen3:14b

The worker passes --model straight to pi. Local and remote models are the same flag.

Library

import { createGitStore, loadProjectTasks, runWorker, createPiRunner } from "@dastardly_duck/pi-agora";

const store = await createGitStore(projectDir);
const report = await runWorker({
	store,
	tasks: loadProjectTasks(projectDir),
	runner: createPiRunner({ piBin: "pi", model: "ollama/qwen3:14b" }),
	maxAttempts: 2,
});

Agent-facing text

Strings the agent parses (task instructions, worker messages) live in src/prompts.ts and follow ASD-STE100 structural rules: short imperative sentences, active voice, one instruction per sentence. verify.sh fixtures follow the same rule — one command per line under set -e.