diff --git a/docs/agent-concurrency-benchmark.md b/docs/agent-concurrency-benchmark.md new file mode 100644 index 0000000..d37a2f4 --- /dev/null +++ b/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 +``` + +## 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 \ No newline at end of file