124 lines
4.0 KiB
Markdown
124 lines
4.0 KiB
Markdown
# 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)
|