kage-research/kugetsu-pi-feature-mapping.md

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