# Kugetsu

**Status:** In Development

Kugetsu is an agent orchestration system that enables parallel task execution across multiple repositories through a hierarchical multi-agent architecture.

## Quick Overview

```
Human (Executive)
    └── PM Agent (Task Coordinator)
            ├── Dev Agent A → Issue 1 → PR
            ├── Dev Agent B → Issue 2 → PR
            └── Dev Agent C → Issue 3 → PR
```

Your focus shifts from doing to overseeing — reviewing PRs, approving plans, managing priorities.

## Core Components

| Component | Implementation | Purpose |
|-----------|---------------|---------|
| **Session Manager** | `kugetsu` CLI | Manages opencode sessions |
| **Chat Interface** | Hermes + Telegram | Mobile UX (Phase 3) |
| **PM Agent** | opencode session | Task coordination |
| **Dev Agents** | opencode sessions | Execute tasks |
| **Communication Hub** | Gitea | Issues, PRs, Comments |

## Session Architecture

| Session | kugetsu ID | Purpose |
|---------|-------------|---------|
| Base Session | `base` | Initial TUI session for forking |
| PM Agent | `pm-agent` | Task coordination |
| Repo PM | `pm-agent-{repo}` | Repo-specific PM (optional) |
| Dev Agent | `issue-{n}` | Per-issue work |

## Current Capabilities

### Phase 1: Remote Access ✅
- SSH access to container
- Tailscale VPN for cross-network access
- See [docs/kugetsu-setup.md](kugetsu-setup.md)

### Phase 2: API Interface 📋
- Planned: REST/CLI API for task assignment
- Status polling
- Webhook support

### Phase 3: Chat Integration 📋
- Telegram bot for mobile UX
- Natural language interaction
- See [docs/kugetsu-chat.md](kugetsu-chat.md)

### Phase 4: Web Dashboard 📋
- Visual task board
- Agent status monitoring
- Read-only dashboards

## Installation

```bash
# Clone repository
git clone https://git.fbrns.co/shoko/kugetsu.git

# Install kugetsu
bash kugetsu/skills/kugetsu/scripts/kugetsu-install.sh

# Setup SSH (optional)
bash kugetsu/skills/kugetsu/scripts/sshd-setup.sh <username>

# Setup Tailscale (optional)
bash kugetsu/skills/kugetsu/scripts/tailscale-setup.sh <username>
```

## Quick Start

```bash
# Initialize base session (requires TTY)
kugetsu init

# Start work on issue
kugetsu start github.com/user/repo#14 "fix bug"

# Continue later
kugetsu continue github.com/user/repo#14 "add tests"

# List sessions
kugetsu list
```

## Documentation

| Document | Purpose |
|----------|---------|
| [kugetsu-architecture.md](kugetsu-architecture.md) | Detailed architecture |
| [kugetsu-chat.md](kugetsu-chat.md) | Phase 3 chat design |
| [kugetsu-setup.md](kugetsu-setup.md) | Setup guides |
| [telegram-setup.md](telegram-setup.md) | Telegram bot setup |
| [SUBAGENT_WORKFLOW.md](SUBAGENT_WORKFLOW.md) | Subagent execution |

## Priority Model

| Priority | Type |
|----------|------|
| 1 | Security |
| 2 | Bugs |
| 3 | Features |
| 4 | Research |

Within each type: Critical > High > Medium > Low