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
mkdir -p ~/.hermes/skills/kugetsu-pm
mkdir -p ~/.hermes/skills/kugetsu-helpers

# 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
ln -sf "$KUGEETSU_DIR/skills/kugetsu-pm ~/.hermes/skills/kugetsu-pm
ln -sf "$KUGEETSU_DIR/skills/kugetsu-helpers" ~/.hermes/skills/kugetsu-helpers

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: Install Helper Scripts

# Copy helper script to PATH
cp "$KUGEETSU_DIR/skills/kugetsu-helpers/scripts/kugetsu-helpers" ~/.local/bin/kugetsu-helper
chmod +x ~/.local/bin/kugetsu-helper

# Verify
kugetsu-helper help

Step 5: Verify Gateway is Running

hermes gateway status
# If stopped:
hermes gateway start

Step 6: 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)

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

Step 7: Verify Setup

# Check kugetsu status
kugetsu list

# Check PM agent exists
kugetsu-helper check-status
# Should output: ok

Step 8: 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-helper 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 missing

# Reinitialize
kugetsu destroy --pm-agent -y
kugetsu init

File Locations

File	Location	Purpose
Chat Agent SOUL	~/.hermes/SOUL-chat.md	Personality
kugetsu-chat skill	~/.hermes/skills/kugetsu-chat/	Routing behavior
kugetsu-pm skill	~/.hermes/skills/kugetsu-pm/	PM Agent docs
kugetsu-helpers	~/.hermes/skills/kugetsu-helpers/	Helper functions
Helper script	~/.local/bin/kugetsu-helper	CLI helper

Architecture Summary

~/.hermes/
├── SOUL-chat.md              # Chat Agent personality
└── skills/
    ├── kugetsu-chat/         # Routing + delegation logic
    ├── kugetsu-pm/           # PM Agent documentation
    └── kugetsu-helpers/      # Shell helpers for terminal()

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

~/.local/bin/
└── kugetsu-helper            # CLI helper script

Testing Plan (Manual)

Test 1: Casual Conversation

Objective: Verify Hermes handles small talk directly without delegation

Step	Action	Expected Result
1	Send hi to @your_bot_username	Bot responds with greeting
2	Send how are you?	Bot responds naturally

Test 2: Task Delegation

Objective: Verify Hermes delegates task to PM Agent via kugetsu-helper

Step	Action	Expected Result
1	Send status? to bot	Bot routes to PM, PM responds
2	Send fix issue #5 to bot	PM agent receives task via opencode
3	Send Work on issue #35 to bot	PM agent creates branch, worktree, PR

Test 3: Error Handling

Objective: Verify graceful error handling

Step	Action	Expected Result
1	Send status? with PM agent stopped	Bot says "PM agent not available"
2	Send status? before kugetsu init	Bot says "kugetsu not initialized"

Debugging

If delegation fails:

# Check Hermes logs
hermes gateway logs

# Check PM agent is running
kugetsu-helper check-status

# Check kugetsu-helper directly
~/.local/bin/kugetsu-helper delegate-to-pm "test"

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