Files

shokollm 202d8ccfbb docs: add Phase 3 chat architecture and overview documentation

- Add docs/kugetsu-chat.md:
  - Model B architecture (separate Chat/PM agents)
  - Session types (chat-agent, pm-agent, pm-agent-{repo}, issue sessions)
  - Hybrid message routing
  - PM Agent modes (notify/silent)
  - Context management (local + Gitea fetch on-demand)
  - Example flows

- Add docs/kugetsu.md:
  - Overview of kugetsu system
  - Quick start guide
  - Links to all documentation

- Update docs/kugetsu-architecture.md:
  - Add Phase 3 architecture section
  - Update success criteria
  - Add Phase 3 design decisions

- Add docs/telegram-setup.md:
  - BotFather bot creation guide
  - Security notes

- Remove ssh-keygen.sh (not needed)

2026-03-30 11:46:12 +00:00

2.9 KiB

Raw Blame History

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

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

Phase 4: Web Dashboard 📋

Visual task board
Agent status monitoring
Read-only dashboards

Installation

# 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

# 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	Detailed architecture
kugetsu-chat.md	Phase 3 chat design
kugetsu-setup.md	Setup guides
telegram-setup.md	Telegram bot setup
SUBAGENT_WORKFLOW.md	Subagent execution

Priority Model

Priority	Type
1	Security
2	Bugs
3	Features
4	Research

Within each type: Critical > High > Medium > Low

2.9 KiB Raw Blame History