From 227ec3a22e4f3427bc68aad87097a855c937e954 Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Mon, 30 Mar 2026 14:25:22 +0000 Subject: [PATCH] docs: add Phase 3a installation guide and update install script - docs/phase3a-setup.md - Complete installation guide for Phase 3a - skills/kugetsu/scripts/kugetsu-install.sh - Updated to reflect v2.2 changes --- docs/phase3a-setup.md | 158 ++++++++++++++++++++++ skills/kugetsu/scripts/kugetsu-install.sh | 55 ++++---- 2 files changed, 183 insertions(+), 30 deletions(-) create mode 100644 docs/phase3a-setup.md diff --git a/docs/phase3a-setup.md b/docs/phase3a-setup.md new file mode 100644 index 0000000..a03618f --- /dev/null +++ b/docs/phase3a-setup.md @@ -0,0 +1,158 @@ +# 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 \ No newline at end of file diff --git a/skills/kugetsu/scripts/kugetsu-install.sh b/skills/kugetsu/scripts/kugetsu-install.sh index 767cc6b..e84c270 100755 --- a/skills/kugetsu/scripts/kugetsu-install.sh +++ b/skills/kugetsu/scripts/kugetsu-install.sh @@ -1,10 +1,13 @@ #!/bin/bash +# kugetsu installation script +# Installs kugetsu CLI and optionally sets up Phase 3a Chat Agent + set -euo pipefail KUGETSU_DIR="${KUGETSU_DIR:-$HOME/.kugetsu}" -BIN_DIR="$KUGETSU_DIR/bin" +BIN_DIR="${BIN_DIR:-$HOME/.local/bin}" -echo "Installing kugetsu to $KUGETSU_DIR..." +echo "Installing kugetsu..." mkdir -p "$BIN_DIR" @@ -13,24 +16,21 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cp "$SCRIPT_DIR/kugetsu" "$BIN_DIR/kugetsu" chmod +x "$BIN_DIR/kugetsu" +echo "kugetsu installed at: $BIN_DIR/kugetsu" + add_to_shell() { local rc_file="$1" - local export_line="export PATH=\"\$HOME/.kugetsu/bin:\$PATH\"" + local export_line="export PATH=\"\$HOME/.local/bin:\$PATH\"" if [ -f "$rc_file" ]; then if grep -q "$export_line" "$rc_file" 2>/dev/null; then - echo "$rc_file already has kugetsu in PATH" + echo "$rc_file already has .local/bin in PATH" else echo "" >> "$rc_file" - echo "# kugetsu - opencode session manager" >> "$rc_file" + echo "# kugetsu and other tools" >> "$rc_file" echo "$export_line" >> "$rc_file" echo "Added to $rc_file" fi - else - echo "" >> "$rc_file" - echo "# kugetsu - opencode session manager" >> "$rc_file" - echo "$export_line" >> "$rc_file" - echo "Created $rc_file with kugetsu PATH" fi } @@ -39,29 +39,24 @@ add_to_shell "$HOME/.zshrc" echo "" echo "=== Verifying installation ===" -if [ ! -f "$BIN_DIR/kugetsu" ]; then - echo "ERROR: kugetsu was not installed correctly." - exit 1 -fi -echo "kugetsu installed at: $BIN_DIR/kugetsu" +"$BIN_DIR/kugetsu" help | head -10 echo "" - echo "Installation complete!" + echo "" -echo "Run this to start using kugetsu immediately:" -echo " export PATH=\"\$HOME/.kugetsu/bin:\$PATH\"" +echo "=== Phase 3a Chat Agent Setup (Optional) ===" +echo "To also install the Chat Agent skills for Phase 3a:" echo "" -echo "Or start a new shell." +echo " 1. Link skills to Hermes:" +echo " mkdir -p ~/.hermes/skills/kugetsu-chat ~/.hermes/skills/kugetsu-pm ~/.hermes/skills/kugetsu-helpers" +echo " ln -sf /path/to/kugetsu/skills/kugetsu-chat ~/.hermes/skills/" +echo " ln -sf /path/to/kugetsu/skills/kugetsu-pm ~/.hermes/skills/" +echo " ln -sf /path/to/kugetsu/skills/kugetsu-helpers ~/.hermes/skills/" echo "" -echo "Usage:" -echo " kugetsu init Initialize base session (requires TTY)" -echo " kugetsu start Start task for issue" -echo " kugetsu continue [msg] Continue existing task" -echo " kugetsu list List all sessions" -echo " kugetsu prune [--force] Remove orphaned sessions" -echo " kugetsu destroy [-y] Delete session for issue" -echo " kugetsu destroy --base [-y] Delete base session" -echo " kugetsu help Show help" +echo " 2. Install Chat Agent SOUL:" +echo " cp /path/to/kugetsu/skills/kugetsu-chat/SOUL.md ~/.hermes/SOUL-chat.md" echo "" -echo "Issue ref format: instance/user/repo#number" -echo "Example: github.com/shoko/kugetsu#14" +echo " 3. Initialize kugetsu (requires TTY):" +echo " kugetsu init" +echo "" +echo "See docs/phase3a-setup.md for full installation guide." \ No newline at end of file