111 lines
2.9 KiB
Markdown
111 lines
2.9 KiB
Markdown
# 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.example.com/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 |