kugetsu/docs/phase3a-setup.md

Kugetsu Phase 3a Installation Guide

Guide for setting up the Kugetsu Chat Agent (Phase 3a) on a new host/container.

Prerequisites

1. Hermes Agent installed and configured
2. Telegram bot created via @BotFather
3. kugetsu CLI installed
4. opencode installed

Step 1: Verify Hermes Installation

hermes version
hermes config show  # Check Telegram is configured

Step 2: Link Skills to Hermes

# Create skill directories
mkdir -p ~/.hermes/skills/kugetsu-chat

# Link skills from kugetsu repo (adjust path as needed)
KUGEETSU_DIR="/path/to/kugetsu"  # e.g., ~/repositories/kugetsu

ln -sf "$KUGEETSU_DIR/skills/kugetsu-chat" ~/.hermes/skills/kugetsu-chat

Step 3: Install Chat Agent SOUL

# Copy SOUL.md to Hermes home (this defines the Chat Agent personality)
cp "$KUGEETSU_DIR/skills/kugetsu-chat/SOUL.md" ~/.hermes/SOUL-chat.md

Step 4: Verify Gateway is Running

hermes gateway status
# If stopped:
hermes gateway start

Step 5: Initialize kugetsu

WARNING: This requires an interactive terminal (TTY) because it spawns the opencode TUI.

You must run this in an interactive shell, not via ssh remote "kugetsu init":

# Option 1: SSH with TTY allocation
ssh -t user@host "kugetsu init"

# Option 2: Connect to existing session and run
ssh user@host
kugetsu init  # Run manually in the SSH session

This creates:

• Base session (for forking dev agents)
• PM Agent session (persistent coordinator, loaded with kugetsu-pm context)

If you get Error: init requires a terminal (TTY), you're running via non-interactive SSH. Use -t flag or connect directly.

Step 6: Verify Setup

# Check kugetsu status
kugetsu status
# Should output: ok

# List all sessions
kugetsu list

Step 7: Test via Telegram

Start a conversation with your bot (@your_bot_username):

Message	Expected
hi	Responds directly (small talk)
status?	Routes to PM Agent
fix issue #5	Routes to PM Agent

Troubleshooting

kugetsu command not found

export PATH="$HOME/.local/bin:$PATH"
# Or add to ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Gateway not responding

hermes gateway restart

PM agent issues

# Diagnose
kugetsu doctor

# Fix (if needed)
kugetsu doctor --fix

# Or reinitialize
kugetsu destroy --pm-agent -y
kugetsu init

kugetsu Commands

Command	Description
kugetsu init	Initialize base + PM agent sessions
kugetsu status	Check if kugetsu is ready
kugetsu delegate <msg>	Send message to PM agent
kugetsu doctor [--fix]	Diagnose and fix issues
kugetsu start <issue-ref> <msg>	Start dev agent for issue
kugetsu continue <issue-ref> <msg>	Continue existing issue session
kugetsu list	List all tracked sessions
kugetsu prune [--force]	Clean up orphaned sessions

File Locations

File	Location	Purpose
Chat Agent SOUL	~/.hermes/SOUL-chat.md	Personality
kugetsu-chat skill	~/.hermes/skills/kugetsu-chat/	Routing behavior
kugetsu	~/.local/bin/kugetsu	Main CLI

~/.kugetsu/ ├── sessions/ │ ├── base.json # Base opencode session │ └── pm-agent.json # PM Agent opencode session ├── index.json # Session registry └── pm-agent.md # PM context (optional, injected at init)

Architecture Summary

~/.hermes/
├── SOUL-chat.md              # Chat Agent personality
└── skills/
    └── kugetsu-chat/        # Routing + delegation via kugetsu CLI

~/.kugetsu/
├── sessions/
│   ├── base.json             # Base opencode session
│   └── pm-agent.json         # PM Agent opencode session
├── index.json                # Session registry
└── pm-agent.md               # PM context (optional)

~/.local/bin/
└── kugetsu                  # Main CLI (handles delegation, status, doctor)

PM Context (Optional)

To customize PM Agent behavior, create ~/.kugetsu/pm-agent.md with additional context. This file is injected into the PM Agent session at init time.

Security Notes

• Never commit ~/.kugetsu/ or SOUL files to version control
• Bot tokens should be in environment variables, not files
• PM agent session IDs are internal - don't expose to users