# 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

```bash
# 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 |