kugetsu/skills/kugetsu/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
kugetsu	Issue-driven session manager for opencode CLI. Manages base sessions and per-issue forked sessions with automatic indexing for headless orchestration.	MIT	Requires opencode CLI, bash, python3, and filesystem access.	author version shoko 2.0

kugetsu - OpenCode Session Manager (Issue-Driven)

Manages opencode sessions with a base session + forked session pattern optimized for headless orchestration.

Installation

For Human Users

Run once on a new host:

. skills/kugetsu/scripts/kugetsu-install.sh

For Agents (Self-Install)

Copy the script to your PATH:

cp skills/kugetsu/scripts/kugetsu ~/.local/bin/kugetsu
chmod +x ~/.local/bin/kugetsu

Architecture

Session Pattern

• Base Session: Created once via TUI, used for forking
• Forked Sessions: One per issue, branched from base via opencode run --fork --session <base>

Directory Structure

~/.kugetsu/
├── sessions/
│   ├── base.json                    # Base session metadata
│   └── github.com-shoko-kugetsu-14.json  # Forked session per issue
└── index.json                       # Maps issue refs to session files

Index File

{
  "base": "ses_abc123",
  "issues": {
    "github.com/shoko/kugetsu#14": "github.com-shoko-kugetsu-14.json"
  }
}

Session File

{
  "type": "base|forked",
  "issue_ref": "github.com/shoko/kugetsu#14",
  "opencode_session_id": "ses_xyz789",
  "created_at": "2026-03-29T18:16:10+02:00",
  "state": "idle"
}

Issue Ref Format

All issue references use the format: instance/user/repo#number

Examples:

• github.com/shoko/kugetsu#14
• gitlab.com/username/project#42
• codeberg.org/user/repo#100

Commands

kugetsu init [--force]

Initialize base session via TUI:

kugetsu init

• Requires a terminal (TTY) to spawn the opencode TUI
• Creates base session once; subsequent runs error unless --force is used
• Stores base session ID in index.json

kugetsu start <issue-ref> <message> [--debug]

Start task for an issue by forking from base session:

kugetsu start github.com/shoko/kugetsu#14 "fix authentication bug"

• Forks new session from base
• Stores mapping in index.json
• Uses opencode run --fork --session <base-session-id> "<message>"

kugetsu continue <issue-ref> <message> [--debug]

Continue work on an existing issue session:

kugetsu continue github.com/shoko/kugetsu#14 "add unit tests"

• Looks up session file from index
• Uses opencode run --continue --session <opencode-session-id> "<message>"

kugetsu list

List all tracked sessions:

kugetsu list

Output:

ISSUE_REF                                          TYPE      SESSION_ID              CREATED
──────────────────────────────────────────────────────────────────────────────────────────────────
(base)                                             base      ses_abc123              N/A
github.com/shoko/kugetsu#14                        forked     ses_xyz789              2026-03-29T18:16:10+02:00

kugetsu prune [--force]

Remove orphaned sessions (files not in index):

kugetsu prune              # Shows what would be deleted
kugetsu prune --force      # Deletes orphaned sessions

• Orphaned = session files in sessions/ but not in index.json
• Always keeps base.json
• Useful after opencode session cleanup

kugetsu destroy <issue-ref> [-y]

Delete session for specific issue:

kugetsu destroy github.com/shoko/kugetsu#14     # Prompts for confirmation
kugetsu destroy github.com/shoko/kugetsu#14 -y  # Skips confirmation

kugetsu destroy --base [-y]

Delete base session (requires explicit --base):

kugetsu destroy --base -y

Workflow Example

# First-time setup (requires TTY)
kugetsu init

# Start work on issue
kugetsu start github.com/shoko/kugetsu#14 "implement feature X"

# Continue later
kugetsu continue github.com/shoko/kugetsu#14 "add tests"

# Continue again
kugetsu continue github.com/shoko/kugetsu#14 "fix failing test"

# List all sessions
kugetsu list

# Clean up orphaned sessions
kugetsu prune --force

# Delete session when done
kugetsu destroy github.com/shoko/kugetsu#14

Headless Operation

This design solves the headless CLI limitation discovered in Issue #14:

1. Problem: opencode run --session <new> doesn't work headlessly (SSE stream terminates)
2. Solution: Fork from existing base session, which works headlessly

The pattern:

• Base session created once via TUI (interactive)
• All subsequent work uses --fork --session <base> or --continue --session <forked>

Recovery

If opencode sessions become out of sync:

1. kugetsu list shows tracked sessions
2. kugetsu prune removes orphaned files
3. For full reset: kugetsu destroy --base -y && kugetsu init

Remote Access via SSH (Optional)

To access kugetsu from a remote machine, SSH setup is required.

Automated Setup

Run the SSH setup script inside your container:

chmod +x skills/kugetsu/scripts/sshd-setup.sh
bash skills/kugetsu/scripts/sshd-setup.sh <username>

Omit <username> to use default user kugetsu.

What It Does

• Checks systemd prerequisite
• Creates non-root user
• Configures SSH for key-only authentication
• Enables passwordless sudo for the user
• Starts sshd via systemd

After Setup

1. Add your SSH public key to ~/.ssh/authorized_keys on the container
2. Configure port forwarding on the host (see docs/kugetsu-setup.md)
3. Connect: ssh -p 2222 <username>@<host-ip>

Remote Usage

Once connected via SSH, kugetsu works the same as local:

kugetsu list
kugetsu start github.com/shoko/kugetsu#14 "fix bug"
kugetsu continue github.com/shoko/kugetsu#14

Documentation

See docs/kugetsu-setup.md for full remote access setup including host-side port forwarding and firewall configuration.

Without kugetsu

If kugetsu is not available, use opencode directly:

# Create base session (requires TTY)
opencode
# Note the session ID from: opencode session list

# Fork for issue
opencode run --fork --session <base-session-id> "task"

# Continue
opencode run --continue --session <forked-session-id> "continue"

Tradeoff: No issue mapping, no index, manual session tracking.