Pi Harness Runtime

⚠️ Beta Notice — Not Production Ready ⚠️ This project is in active development. Core features work.

Autonomous AI coding harness for pi: local token tracking + provider mirror + task orchestration.

Two Flavors

1. /usage — Token Tracking (stable ✅)

Codex-style usage tracking with local tokens + provider mirror.

2. /harness — Autonomous Coding Loop (beta 🔨)

Give the runtime a requirement. It keeps working, survives interruption, and returns with code ready for review.

Install

pi install npm:pi-harness-runtime

Requires Pi v0.37.3+.

Usage Commands

/usage              # show full status (local tracking + provider mirror)
/usage refresh     # force refresh quota from provider console
/usage today       # today's usage + 5h window
/usage week        # this week's usage + lifetime totals
/usage reset       # clear provider mirror

Harness Commands

/harness start <requirement>   # Start a new harness job (beta)
/harness status               # Show current job status
/harness tasks                # List all tasks
/harness pause                # Pause when quota low
/harness resume               # Resume after quota reset
/harness cancel               # Cancel job

Example Session

/harness start Build a REST API with JWT authentication

# Runtime creates task graph:
# task-001: Analyze requirements → ready
# task-002: Implement API → depends on task-001
# task-003: Write tests → depends on task-002
# task-004: Code review → depends on task-003

/harness status
# Job: job-123, Status: running
# Tasks: 1/4 done, 1 running

# When quota runs low:
/harness pause
# Job paused. Resume when quota resets.

# When quota resets:
/harness resume
# Job resumed. Continue working.

# When all tasks complete:
/harness status
# Job: job-123, Status: ready_for_client
# Tasks: 4/4 done ✓

Architecture

pi-harness-runtime/
├── index.ts                    # Extension entry point
├── footer-status.ts            # Footer bar renderer (local vs. mirror mode)
├── mirror.ts                   # Per-provider quota mirror (mirror.json)
├── harness/
│   ├── job-state-machine.ts   # 14-state lifecycle machine
│   ├── task-graph.ts           # DAG-based task management
│   ├── master-planner.ts       # Requirement → task graph
│   ├── loop-runtime.ts         # Core execution loop
│   ├── repair-engine.ts        # Auto-fix failures
│   ├── blackboard.ts           # Agent coordination
│   ├── context-window-manager.ts # Context tracking
│   ├── agent-handoff.ts        # Clean agent transitions
│   ├── e2e/
│   │   ├── minimax-quota-scraper.ts  # Playwright MiniMax scraper
│   │   └── playwright-runner.ts       # Browser automation
│   └── project-detector/
│       └── detector.ts         # Auto-detect project type
├── packages/
│   ├── cookie-sanitizer/       # Live cookie-file sync via chokidar
│   ├── providers/              # MiniMax, OpenAI, Codex adapters
│   ├── quota-manager/          # Quota signal collection
│   ├── auth/                   # MiniMax browser auth
│   └── worktree/              # Git worktree per task
└── skills/
    └── harness-runtime/
        └── SKILL.md           # Skill documentation

Job State Machine

created → planning → queued → running → testing → reviewing
    ↓        ↓         ↓        ↓         ↓
cancelled  blocked   waiting_human  repairing  ready_for_client
                                        ↓            ↓
                                  paused_quota    archived

Key Features

• Resumable: Every state change is checkpointed to disk
• Quota-aware: Detects quota exhaustion, pauses, resumes after reset
• Provider-agnostic: MiniMax, OpenAI, Claude adapters
• Task DAG: Dependencies tracked, topological execution
• Auto-repair: Failure classification + retry with exponential backoff
• E2E testing: Scenario-based Playwright integration (coming soon)
• Project detection: Auto-detects Frappe, Next.js, React, Django, Laravel
• Per-provider mirror: Each LLM provider maintains its own quota record

Data Directory

All data stored locally in ~/.pi/:

~/.pi/
├── usage-status/         # /usage data
│   ├── usage.jsonl
│   └── mirror.json        # per-provider quota mirror
├── harness/            # /harness data
│   └── jobs/
│       └── <job-id>/
│           ├── checkpoint.json
│           ├── events.jsonl
│           ├── task-graph.json
│           ├── blackboard/
│           └── repair-tasks.jsonl
└── okf/               # (optional) Your custom OKF knowledge

Custom OKF Knowledge (Optional)

Create ~/.pi/okf/ to add your custom knowledge that the runtime reads during context compilation:

~/.pi/okf/
├── <skill-name>.md      # Your custom skill/procedure
├── <domain>.md          # Domain-specific knowledge
└── <project>.md        # Project-specific rules

The runtime automatically detects and reads these files. If the folder doesn't exist, compilation proceeds without them.

Example:

# my-custom-skill

## When to use

This skill applies when...

## Procedure

1. Step one
2. Step two

See packages/context-compiler/ for how OKF concepts are loaded.

Safety Properties

• ✅ Local-first: All data stays on disk
• ✅ No credentials stored: No passwords, tokens, or cookies
• ✅ Human-on-the-loop: Clear intervention points
• ✅ Checkpointed: Resume from any state
• ✅ Idempotent: Safe to run multiple times

Testing

bun test   # 131+ tests passing

Automatic Quota Fetching

Quota data is automatically surfaced per-provider:

Provider	Source	Notes
MiniMax	Live cookie-file watch + Playwright scrape	Drop folder: ~/.pi-harness-runtime/cookies/
OpenAI / OpenAI Codex	TUI message capture	Signal on first limit hit
GLM (Z.ai / Zhipu)	TUI message capture	Signal on first limit hit
Anthropic	TUI message capture	Signal on first limit hit
OpenRouter	TUI message capture	Signal on first limit hit
Other / unknown	(no data — footer shows hint)	—

The footer line carries the provider label, so you always know which LLM the data is from:

MiniMax:  5h: 92% left · week: 80% left            # continuous (cookie scrape)
OpenAI:   5h: -- · week: -- (no signal yet)          # pending first limit hit
GLM:      limit hit (tokens), reset 2026-07-23T17:28:00Z   # TUI signal observed
MiniMax:  cookies not found — drop any cookie file into
          ~/.pi-harness-runtime/cookies/

MiniMax Setup (one-time)

The runtime watches ~/.pi-harness-runtime/cookies/ for cookie files. Drop any cookie export there — it syncs within ~1 second:

1. Install EditThisCookie Chrome extension → export from platform.minimax.io

2. Create the drop folder:

   mkdir -p ~/.pi-harness-runtime/cookies
   

3. Drop your cookie file in the folder — any filename, any format (Netscape .txt or EditThisCookie JSON .json):

   cp ~/Downloads/platform.minimax.io_cookies.txt \
      ~/.pi-harness-runtime/cookies/
   # …or use the EditThisCookie JSON export — same folder works.
   

   The cookie-sanitizer package (@pi-harness/cookie-sanitizer) runs chokidar on this folder, normalizes everything to standard Netscape, and writes the canonical cache at ~/.config/minimax-cookies.txt. Live update latency: <1 second after drop.

4. Done! Quota auto-refreshes every ~15 minutes. Cookie file changes sync immediately.

Override: set QUOTA_COOKIE_FILE=/path/to/your/cookies.txt to bypass the sanitizer and read a specific file directly.

Other Providers

No setup needed. The runtime reads TUI messages and captures quota-exhaustion signals. Once any limit is hit (e.g. OpenAI: context length exceeded, reset in 3 hr 27 min), the footer updates immediately and the data persists in mirror.json.

Roadmap

• Core harness infrastructure (job state machine, task graph)
• Master planner
• Repair engine
• Shared blackboard
• MiniMax Web automatic quota detection
• Cookie-file drop folder + live sync (cookie-sanitizer)
• Per-provider quota mirror (mirror.json keyed by provider)
• Multi-provider TUI signal capture (OpenAI, GLM, Anthropic, OpenRouter)
• E2E test engine integration
• Claude adapter
• Production stress testing
• RFC-0101: Autonomous Operations Runtime (background execution, task inbox, lease protocol)

License

MIT © 2026 MooCoding

Related

• pi-coding-agent — Underlying pi agent
• context-mode — Context window tracking
• pi-web-access — Web search for pi

RFCs

The project tracks 101 design documents:

RFC	Title	Status
0001–0034	Loop Runtime, Provider Adapter, Quota Manager, Playwright, Git Worktree, Checkpoint, Scheduler, Provider Router, Shared Context, Context Window Manager, Shared Blackboard, Agent Handoff, E2E Test Engine, Project Detector, Job State Machine, Task Graph, Master Planner, Repair Engine, Auto Compact & Continue, Output Token Limit, Partial Response Recovery, Notification Center, Local Browser Agent, Local Runtime Agent, Command Executor, Workspace Manager, Runtime API, Policy Engine, DeepAgents Adapter, Agent Worker Interface, Provider Adapter SDK, Checkpoint Engine, Session Manager	Proposed
0035–0100	Observability, Roadmap V1, Code Review, Code Generation, Framework Detector, Test Data Generator, Framework Plugin SDK, Prompt Compiler, Context Compiler, Requirement Compiler, Task Compiler, Project Analyzer, Dependency Analyzer, Repo Knowledge Graph, Code Merge Engine, Conflict Resolution, Documentation Generator, Capability Registry, Skill Registry, Model Registry, Cost Optimizer, Performance Optimizer, Evaluation Engine, Learning Engine, Experience Replay, Memory Engine OKF, Frappe/Next.js/React/Django/Laravel/Generic Web Plugins, CLI Plugin SDK, MCP Adapter, A2A Adapter, Codex Adapter, Requirement Intake, Project Bootstrap, Architecture Generator, Sprint Planner, Milestone Manager, Backlog Manager, Human Approval Gate, Release Manager, Version Manager, Deployment Pipeline, Multi-User Runtime, RBAC, Audit Trail, Dashboard, Analytics, Distributed Runtime, Cluster Manager, Runtime Federation, High Availability, Disaster Recovery, + 17 Autonomous Architectures	Proposed
0101	Autonomous Operations Runtime — durable Task Inbox, Background Worker, Task Lease protocol, Privilege Broker, Approval Class policy engine, abstract Scheduler, Notification pipeline, Recovery semantics	Proposed

Why This Matters

These RFCs address real runtime failures:

• MiniMax auto-compacts but does not automatically resume.
• A model may stop because max output token limit is reached.
• Partial responses must be preserved and continued.
• The human needs mobile/tablet notifications.
• Headless servers cannot open interactive login windows for MiniMax usage console.
• The runtime must continue executing after the chat session ends, the SSH session disconnects, or the provider quota exhausts.