ede47439b0
Issue #105: opencode run --fork/--continue --dir <path> fails to create sessions Root cause: The --dir flag breaks session creation in opencode. Sessions fail to be created when --dir is used with --fork or --continue. Solution: Instead of using --dir flag, create worktrees inside the parent session's directory and use 'cd $worktree_path && opencode run ...' to change directory before running opencode. Key changes: - Worktrees now created at $PWD/.kugetsu-worktrees/{issue-ref}/ instead of $WORKTREES_DIR/{issue-ref}/ - .kugetsu-worktrees is a hidden directory (git ignored by default) - cmd_start and cmd_continue now use 'cd && opencode run' instead of 'opencode run --dir' This approach works because: 1. Worktree is inside parent's directory tree (permission granted) 2. cd properly changes working directory before opencode runs 3. Session gets created with correct directory set 4. No .gitignore entry needed (. prefix makes it hidden from git)
Kugetsu
Name background: Kugetsu (月掴, "grasping the moon") is derived from Jujutsu Kaisen's "Tokusa no Kage Boujutsu" (Shadow Art Style) — a technique that summons up to ten different creatures from the user's shadow. This project embodies the concept of one orchestrator managing multiple specialized agents working in parallel.
Overview
Kugetsu is an agent orchestration system that enables parallel task execution across multiple repositories. Inspired by the IT department metaphor:
- Human acts as executive, reviewing and approving
- PM (Project Manager) Agent coordinates and delegates tasks
- Coding Agents execute tasks autonomously on assigned issues
The core idea: instead of working through issues one-by-one, a PM spawns multiple coding agents in parallel — similar to Hermes running multiple tasks, but scaled to a full team workflow.
Why
When you have 10 issues, typically you work through them sequentially. With Kugetsu:
- PM prioritizes and splits tasks
- Coding agents work in parallel on their own branches
- PM reviews and merges to a release branch
- Human provides final approval to master/main
This means your focus shifts from doing to overseeing — reviewing PRs, not writing code.
Status
Phase 3: Chat Integration (Implemented)
- PM Agent with git worktree isolation per session
- Chat Agent via Telegram gateway
- Parallel capacity testing tool available
See Architecture for full system design and phase status.
Capacity Planning
Based on parallel capacity testing (tools/parallel-capacity-test/):
| Resource | Value |
|---|---|
| Memory per agent | ~340 MB |
| Recommended max agents | 5 |
| Timeout threshold | 8+ agents |
| Memory limit | 1 GB per agent (configurable) |
Observed Behavior
- 1-5 agents: 100% success rate, ~6-9s avg response time
- 8+ agents: Timeouts occur due to resource contention
- Scaling is roughly linear up to 5 agents
Recommendations
- Limit max parallel agents to 5 for stable operation
- Monitor memory usage when scaling beyond 3 agents
- Configure memory limit via
--memory-limitflag based on available RAM
Documentation
- Architecture — Full system design
- Research Index — All research topics
License
MIT