# Agent Concurrency Benchmark

**Date:** 2026-04-01  
**Hardware:** 8GB RAM, 16 CPU cores

## Test Results

| Limit (PM+Dev) | Status | Rejection Test | Notes |
|----------------|--------|---------------|-------|
| 1 | ✓ Works | 1 dev rejected (PM=1, at limit) | Too strict for normal use |
| 3 | ✓ Works | 4th dev rejected (PM + 3 devs = 4, at limit) | Recommended |
| 5 | ✓ Works | 6th dev rejected (PM + 5 devs = 6, at limit) | Works, monitor memory |

## Architecture

OpenCode is a **cloud client** - agents run on OpenCode's server (MiniMax), not locally.

```
┌─────────────────┐         ┌─────────────────┐
│   Local Host    │         │   OpenCode      │
│                 │  HTTPS  │   Server        │
│  kugetsu CLI    │◄───────►│   (MiniMax)     │
│  worktrees/     │  API    │   Agents run    │
│  sessions/      │  Key    │   here          │
│  opencode.db    │         │                 │
└─────────────────┘         └─────────────────┘
     ~4MB per agent             Server-side
     (worktree only)            memory (unknown)
```

## Memory Analysis

### Local Memory (Measurable)

| Component | Memory | Notes |
|-----------|--------|-------|
| Per worktree | ~600KB | Git repository clone |
| Sessions dir | ~28KB | JSON metadata |
| opencode.db | ~93MB | Local cache (148 sessions, 10K+ messages) |
| **Total 5 agents** | **~4MB** | Worktrees only, negligible |

**Conclusion:** Local RAM does NOT limit agent count. A 1GB or 2GB system can run MAX=10 agents.

### Server Memory (Not Measurable)

- OpenCode server runs on MiniMax's infrastructure
- No local process to measure RSS/memory
- Agent computation happens server-side
- Memory limit determined by OpenCode service, not local hardware

### Local Bottleneck

The only local constraint is `MAX_CONCURRENT_AGENTS` limit, which:
- Counts session files (PM + dev agents)
- Enforced in kugetsu before spawning
- Prevents resource overload on OpenCode server

## Behavior

With MAX_CONCURRENT_AGENTS=N:
- PM agent counts toward the limit (along with all dev agents)
- At limit: NEW sessions are REJECTED
- Existing sessions can ALWAYS be continued (--continue doesn't count toward limit)
- PM is still accessible when at limit (user can wait or cancel tasks)

## Configuration

Default limit is set to **5 concurrent agents** in `skills/kugetsu/scripts/kugetsu`:

```bash
MAX_CONCURRENT_AGENTS="${MAX_CONCURRENT_AGENTS:-5}"
```

The limit can be overridden via environment variable:
```bash
MAX_CONCURRENT_AGENTS=3 kugetsu start <issue> <message>
```

## Implementation

Session counting approach (vs broken slot mechanism):

```bash
# Count all session files except base.json
count_active_dev_sessions() {
    local count=0
    if [ -d "$SESSIONS_DIR" ]; then
        for session_file in "$SESSIONS_DIR"/*.json; do
            if [ -f "$session_file" ]; then
                local filename=$(basename "$session_file")
                if [ "$filename" != "base.json" ]; then
                    count=$((count + 1))
                fi
            fi
        done
    fi
    echo "$count"
}
```

## Session Files

```
~/.kugetsu/sessions/
  base.json                    - base session (NOT counted)
  pm-agent.json                - PM agent (COUNTED)
  github.com-user-repo#1.json  - dev agent (COUNTED)
  github.com-user-repo#2.json  - dev agent (COUNTED)
```

## Recommendations

- **1 agent:** Too strict - just PM + 0 dev agents
- **3 agents:** Recommended - PM + 2 dev agents, leaves room for PM to coordinate
- **5 agents:** Works - PM + 4 dev agents, monitor OpenCode service limits
- **More than 5:** Not tested - depends on OpenCode server capacity

## Session Cleanup

Sessions persist until explicitly destroyed:
- `kugetsu destroy <issue-ref>` - destroy specific session
- `kugetsu destroy --pm-agent -y` - destroy PM agent
- PM should destroy sessions after PR merged (on natural breakpoints)