docs/agent-concurrency-benchmark.md

@@ -0,0 +1,43 @@
+# Agent Concurrency Benchmark
+
+**Date:** 2026-04-01  
+**Hardware:** 8GB RAM, 16 CPU cores
+
+## Test Results
+
+| Concurrent Agents | Status | Memory Usage | Notes |
+|-------------------|--------|--------------|-------|
+| 1 | ✓ Works | ~1.1GB idle | Baseline test |
+| 3 | ✓ Works | ~1.1GB idle | Default limit |
+| 5 | ✓ Works | ~1.1GB idle | Increased limit |
+
+## 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>
+```
+
+## Observations
+
+1. **Idle Memory:** ~1.1GB used even with sessions idle (includes system buffers)
+2. **CPU:** 16 cores available - sufficient for multiple agents
+3. **No Active Processes:** When sessions are idle, opencode processes are not actively running
+
+## Recommendations
+
+- **1-3 agents:** Safe for most workloads on 8GB RAM systems
+- **5 agents:** Works but monitor memory if running additional services
+- **More than 5:** Not tested - may require more RAM
+
+## Notes
+
+- Each agent session creates a worktree in `~/.kugetsu/worktrees/`
+- Sessions are forked from base session using `opencode run --fork --continue --session`
+- Idle sessions consume minimal resources