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:

MAX_CONCURRENT_AGENTS="${MAX_CONCURRENT_AGENTS:-5}"

The limit can be overridden via environment variable:

MAX_CONCURRENT_AGENTS=3 kugetsu start <issue> <message>

Implementation

Session counting approach (vs broken slot mechanism):

# 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)

4.0 KiB Raw Blame History