Implementation Plan: Pi Integration for Kugetsu

Overview

This document outlines the implementation roadmap for replacing OpenCode with Pi (agent-core) in the Kugetsu orchestration system.

Current Status: ✅ Levels 1-4 Complete

All core implementation levels are complete. See README.md for summary.

Implementation Levels

Level 1: Proof of Concept (POC) ✅ COMPLETE

Goal: Validate Pi works in your environment

Results:

Pi agent works ✅
Tool execution works ✅
Memory: ~130MB RSS ✅
stepfun free model works ✅

File: level1.ts

Level 2: Basic Integration ✅ COMPLETE

Goal: Shadow + Manager + Tools

Results:

Shadow class with context isolation ✅
Shadow Manager (spawn/terminate/track) ✅
Tool registry (read, write, edit, bash, grep, ls) ✅
Concurrency control ✅

File: level2.ts

Level 3: Production Features ✅ COMPLETE

Goal: Queue + Checkpoint + Context Management

Completed:

Task status tracking ✅
Retry with backoff ✅
Checkpoint save/load ✅
Context pruning ✅
Priority queue ✅
Backpressure ✅

Files: level3.ts, level3b.ts, level3c.ts

Level 4: Hermes Integration ✅ COMPLETE

Goal: Connect to Hermes

Completed:

HTTP server ✅
Webhook endpoint ✅
Tool implementation guide ✅
HTTP vs Direct Spawn comparison ✅

Files: level4.ts, pi_agent_tool.py, hermes-tool-guide.md

What's Left

Priority	Item	Notes
P2	Full Hermes integration	Test with actual Hermes
P2	Direct spawn option	Alternative to HTTP
P1	Production hardening	Rate limiting, logging

Quick Reference

Run Tests

# Level 1: Basic agent
npx tsx level1.ts

# Level 2: Shadow + Manager
npx tsx level2.ts

# Level 3: Queue system
npx tsx level3c.ts

# Level 4: HTTP server
npx tsx level4.ts

Key Findings

Metric	OpenCode	Pi
Memory/agent	340MB	~80MB
Max concurrent	5	15-20
Improvement	-	~70% less memory

Document History

Date	Update
2026-04-08	Initial plan created
2026-04-08	Levels 1-4 complete

2.2 KiB Raw Blame History