---
name: kugetsu-helpers
description: Helper tools for Hermes to interact with kugetsu. Provides routing, delegation, and status functions.
license: MIT
compatibility: Requires Hermes agent, kugetsu CLI, opencode sessions.
metadata:
  author: shoko
  version: "1.0"
---

# kugetsu-helpers - Hermes Tools for Kugetsu

Provides tools/functions for Hermes to route messages and delegate to the PM Agent.

## Overview

This skill enables Hermes (as Chat Agent) to interact with kugetsu-managed opencode sessions.

## Tools

### kugetsu_get_pm_session

Gets the PM Agent session ID from kugetsu index.

```bash
kugetsu_get_pm_session
```

**Returns:** PM agent session ID string, or empty if not initialized

**Example:**
```
PM_SESSION=$(kugetsu_get_pm_session)
echo "PM Agent: $PM_SESSION"
```

### kugetsu_delegate_to_pm

Delegates a task to the PM Agent via opencode.

```bash
kugetsu_delegate_to_pm "<task message>"
```

**Arguments:**
- `task message`: The task to delegate (e.g., "fix issue #5")

**Returns:** PM Agent response (may be multi-line)

**Example:**
```
kugetsu_delegate_to_pm "User wants to fix issue #5 in github.com/shoko/kugetsu"
```

### kugetsu_check_status

Checks kugetsu initialization status.

```bash
kugetsu_check_status
```

**Returns:** Status string indicating:
- "ok" - kugetsu initialized, PM agent running
- "kugetsu_not_initialized" - Run kugetsu init first
- "pm_agent_missing" - PM agent not found

### kugetsu_list_sessions

Lists all kugetsu-managed sessions.

```bash
kugetsu_list_sessions
```

**Returns:** Formatted list of sessions

### kugetsu_create_dev_session

Creates a Dev Agent session for an issue.

```bash
kugetsu_create_dev_session "<issue-ref>" "<task>"
```

**Arguments:**
- `issue-ref`: Issue reference (e.g., "github.com/shoko/kugetsu#5")
- `task`: Task description for the dev agent

**Returns:** Session creation status

## Implementation

These tools are implemented as shell functions that Hermes can call via `terminal()`.

### Direct Implementation (Recommended)

Add to Hermes SOUL.md as custom tools:

```
You have access to kugetsu via terminal commands:

- kugetsu_get_pm_session: Get PM agent session ID
- kugetsu_delegate_to_pm <task>: Delegate to PM agent
- kugetsu_check_status: Check kugetsu status
```

### Tool Definition Format

Hermes tools should call these functions via terminal():

```python
{
  "name": "kugetsu_delegate",
  "description": "Delegate a task to the PM Agent",
  "parameters": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "Task to delegate to PM Agent"
      }
    },
    "required": ["task"]
  }
}
```

## Usage in Hermes

### SOUL.md Integration

Add to your SOUL.md:

```
You can interact with kugetsu to route tasks:

1. Get PM agent session: terminal(command="kugetsu_get_pm_session")
2. Delegate to PM: terminal(command="kugetsu_delegate_to_pm 'fix issue #5'")
3. Check status: terminal(command="kugetsu_check_status")
```

### Routing Logic

```
User message → Hermes
    │
    ├─ Small talk → respond directly
    │
    └─ Task request → terminal(kugetsu_delegate_to_pm "<task>")
            │
            └─ PM Agent response → relay to user
```

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| "kugetsu not initialized" | Run `kugetsu init` | Inform user |
| "pm_agent_missing" | PM agent not created | Run `kugetsu init` |
| "session not found" | opencode session expired | May need reinit |

## Files

- `scripts/kugetsu-helpers.sh` - Shell implementations
- `SKILL.md` - This documentation