227ec3a22e
- docs/phase3a-setup.md - Complete installation guide for Phase 3a - skills/kugetsu/scripts/kugetsu-install.sh - Updated to reflect v2.2 changes
158 lines
4.0 KiB
Markdown
158 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
hermes version
|
|
hermes config show # Check Telegram is configured
|
|
```
|
|
|
|
## Step 2: Link Skills to Hermes
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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"`:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
export PATH="$HOME/.local/bin:$PATH"
|
|
# Or add to ~/.bashrc
|
|
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
|
```
|
|
|
|
### Gateway not responding
|
|
```bash
|
|
hermes gateway restart
|
|
```
|
|
|
|
### PM agent missing
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
## 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 |