feat(phase3): add notification system and kugetsu notify command
Phase 3c implementation - Notification System: ### New kugetsu commands: - `kugetsu notify list` - Show unread notifications from PM Agent - `kugetsu notify clear` - Mark notifications as read ### Notification system: - PM Agent writes task events to ~/.kugetsu/notifications.json - Events: task_complete, task_blocked, task_assigned - Supports issue_ref and gitea_url for linking - Hermes/Chat Agent reads notifications on user messages ### kugetsu-pm v2.0: - Updated documentation with notification behavior - PM Agent monitors Gitea for task completion - Two review modes: PM reviews immediately OR asks dev if ready - Notification triggers documented ### File renamed: - phase3a-setup.md → kugetsu-chat-setup.md (more descriptive) ### Hermes gateway analysis: - Gateway is a client (connects to Telegram), not a server - Cannot push messages directly to Telegram from external process - Notifications stored locally for Hermes to pick up on next user message
This commit is contained in:
shokollm
170
docs/kugetsu-chat-setup.md
Normal file
170
docs/kugetsu-chat-setup.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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
|
||||
|
||||
# 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
|
||||
|
||||
```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: Verify Gateway is Running
|
||||
|
||||
```bash
|
||||
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"`:
|
||||
|
||||
```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, 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```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 issues
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user