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

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"
}

Observations

Idle Memory: ~1.1GB used even with sessions idle (includes system buffers)
CPU: 16 cores available - sufficient for multiple agents
No Active Processes: When sessions are idle, opencode processes are not actively running
PM counts: PM agent session counts toward MAX_CONCURRENT_AGENTS limit

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 memory
More than 5: Not tested - may require more RAM

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)

2.6 KiB Raw Blame History