# Kugetsu vs Pi Feature Mapping

## Overview

This document maps Kugetsu's current functionality to what Pi (agent-core) provides, helping understand what to keep, what to modify, and what to build new.

---

## Kugetsu → Pi Feature Comparison

| Kugetsu Function | Pi Has It? | Notes |
|-----------------|------------|-------|
| **Queue system** | ❌ No | Pi is single-agent runtime |
| **Session tracking** | ⚠️ Partial | Events (`agent_end`, `turn_end`), but no built-in persistence |
| **Worktree management** | ❌ No | Git operations not included in Pi |
| **PM Agent logic** | ❌ No | Task coordination is your responsibility |
| **Parallel capacity control** | ❌ No | You control concurrency |
| **Resource monitoring** | ❌ No | You measure memory/CPU |
| **Context isolation** | ✅ Yes | Each `Agent` instance is separate |
| **Tool execution hooks** | ✅ Yes | `beforeToolCall`, `afterToolCall` |
| **Rich event stream** | ✅ Yes | Full lifecycle events |
| **Checkpoint/save state** | ❌ No | You build this |

---

## What Stays from Kugetsu

| Component | What You Keep | What Changes |
|-----------|--------------|--------------|
| **Queue/Orchestration** | ✅ Keep | Replace with simpler implementation since Pi is lighter |
| **Worktree logic** | ✅ Keep | Works the same |
| **PM Agent** | ✅ Keep | Runs as a Pi agent instead of OpenCode session |
| **Telegram/Hermes bridge** | ✅ Keep | No changes needed |
| **Capacity testing** | ✅ Keep | Retest with Pi for new benchmarks |
| **CODING_GUIDELINES.md** | ✅ Keep | Pi loads AGENTS.md or CLAUDE.md |

---

## What Changes

| Component | Before (OpenCode) | After (Pi) |
|-----------|-------------------|-------------|
| **Agent runtime** | ~340MB per agent | ~80MB per agent |
| **Session isolation** | Worktree-based | Worktree + context tagging |
| **Crash detection** | Missing/silent | Event subscription + heartbeats |
| **Checkpoint** | None | Built into Shadow class |
| **Message streaming** | Limited | Rich event stream |

---

## The New Architecture

```
Before:
┌─────────────────────────────────────────────┐
│ Kugetsu (Queue + Orchestration)             │
│  ├── Queue system (custom)                  │
│  ├── Worktree management                    │
│  ├── PM Agent (OpenCode session)            │
│  └── Coding Agents (OpenCode sessions)      │
│       └── ~340MB each, context in session   │
└─────────────────────────────────────────────┘

After:
┌─────────────────────────────────────────────┐
│ Kugetsu (Queue + Orchestration)             │
│  ├── Queue system (simplified, lighter)     │
│  ├── Worktree management                    │
│  ├── PM Agent (Pi agent)                    │
│  └── Coding Agents (Pi "Shadows")           │
│       └── ~80MB each, context isolation     │
│            ├── Event-driven tracking        │
│            ├── Checkpoint support           │
│            └── Rich hooks for UX            │
└─────────────────────────────────────────────┘
```

---

## What You Build New

Since Pi doesn't include these, you add them in Kugetsu:

1. **Shadow Manager**
   - Spawns Pi agents
   - Tracks state
   - Manages lifecycle

2. **Queue with Concurrency Control**
   - Simpler than before (less resource contention)
   - Parallel capacity: 15-20 shadows on 4GB RAM

3. **Event-Driven Session Tracking**
   - Subscribe to `agent_end`, `agent_error`
   - Know immediately when a session ends/crashes
   - No more "silent death"

4. **Checkpoint System**
   - Save state every N seconds
   - Recover from last checkpoint on crash

5. **Resource Monitor**
   - Track memory per shadow
   - Auto-scale based on availability

---

## Why This Works Better

| Problem | Before (OpenCode) | After (Pi) |
|---------|-------------------|------------|
| **Session poisoning** | Context bleeds between agents | Strict `convertToLlm` filtering |
| **Silent crashes** | Process dies, no trace | Event subscription catches this |
| **Memory exhaustion** | 5 max, then queue | 15-20 max, more headroom |
| **UX in headless** | Limited streaming | Rich events rebuild TUI |

---

## Summary

- **Keep**: Queue, worktree, PM agent logic, Hermes bridge
- **Modify**: Session isolation (add context tagging), event handling
- **Build**: Shadow manager, checkpointing, resource monitor
- **Gain**: 70% less memory, observable sessions, TUI-like headless UX