piocloop

A Python TUI that orchestrates the PI coding agent to execute tasks from a PLAN.md file iteratively, one session at a time.

piocloop is a port of pyocloop — same concept, but it drives pi --mode rpc over stdin/stdout JSONL instead of an OpenCode HTTP server plus SSE stream. That change, plus a real watchdog, fixes the hangs documented in ANALYSIS.md.

How it works

1. piocloop starts a pi --mode rpc subprocess
2. On each iteration it starts a fresh session, sends your loop prompt (with the plan file path injected), and waits for agent_settled
3. PI reads the plan, executes the next task, marks it [x], and appends <plan-complete> when everything is done
4. The TUI shows live progress: task counter, progress bar, current task, token count, cost, and elapsed/average time per iteration
5. The loop stops when PI writes <plan-complete> — or when the watchdog, an error streak, a stall, or --max-iterations intervenes

Requirements

• Python 3.11+
• pi on your PATH, configured with a provider (developed against pi 0.82.1)

npm install -g @earendil-works/pi-coding-agent

Installation

git clone https://github.com/rbarzic/piocloop
cd piocloop
pip install .

Usage

piloop doctor                    # check pi is installed and reachable
piloop bootstrap .               # create starter PLAN.md and .loop-prompt.md
piloop run --model zai/glm-5.2

Using an OpenRouter model

Set your OpenRouter API key, then prefix the OpenRouter model ID with openrouter/. For example, Kimi K3 is moonshotai/kimi-k3 on OpenRouter:

export OPENROUTER_API_KEY="your-openrouter-api-key"
piloop run --model openrouter/moonshotai/kimi-k3

You can check that PI's model catalog contains it with:

pi --list-models openrouter | grep kimi-k3

piloop run

Keys: S start · Space pause · A abort current iteration · R retry · Q quit.

Plan format

- [ ] a task to do
- [x] a completed task
- [MANUAL] something a human must do — never attempted, excluded from progress
- [BLOCKED: reason] something the agent could not finish

The run ends when the agent appends, at the start of a line:

<plan-complete>summary of what was done</plan-complete>

Agent skill (optional)

skills/piocloop-setup/ is an Agent Skills package you can copy into your own agent so it can set up piocloop runs for you — turning "for each of these 40 items, do X" into a correctly formatted PLAN.md and .loop-prompt.md. It is not loaded automatically; install it only if you want it:

cp -r skills/piocloop-setup ~/.pi/agent/skills/     # PI
cp -r skills/piocloop-setup ~/.claude/skills/       # Claude Code

See skills/README.md for other harnesses and for pointing pi at this checkout without copying.

Differences from pyocloop

-a/--agent and -p/--port are gone: PI has no named-agent concept (use --append-system-prompt / --skill) and no server to bind.

Why the rewrite is more reliable

ANALYSIS.md documents the pyocloop defects that motivated this port — verified against a live OpenCode server, not inferred. The two that caused silent hangs:

• the server's stdout pipe was never drained after startup, so the OS pipe eventually filled and the server blocked in write() and stopped serving;
• the loop's idle wait had no deadline, and its polling fallback tested a session.idle field that OpenCode does not return — so a single missed SSE event hung the run forever.

piocloop's design rules (DESIGN.md §4) are the direct response: every pipe gets a drainer, every wait gets a deadline, and lack of progress is a first-class state. The test suite mutation-checks the first two — removing either fix makes the corresponding regression test hang.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest tests/ -q

Tests run against tests/fake_pi.py, a stub agent — no network, no API key and no LLM required.

License

MIT