[arkaccess]

Issue #5 asks whether multiple Claude agents can work on a project at once to finish it faster. They can: the unified orchestrator (parallel_orchestrator.py) already runs up to 5 coding agents at the same time. The README just never mentioned it. This PR documents the feature and fixes wrong CLI flags in CLAUDE.md.

Changes

• README.md: new "Parallel Mode (Multiple Agents)" section under How It Works. It covers:
  • how to turn it on (the concurrency slider in the UI, or --concurrency N on the CLI)
  • how features are claimed and scheduled around dependencies
  • per-agent browser sessions
  • regression agents, batching and the hard process limits
  • trade-offs: token use and rate limits, and the shared working tree
• CLAUDE.md: replaced flags that don't exist. --parallel --max-concurrency 3 is now --concurrency 3, --batch-features is now --feature-ids, and --testing-batch-features is now --testing-feature-ids. I took the correct names from autonomous_agent_demo.py's argparse definitions.

Verification

• Checked every claim against the code: MAX_PARALLEL_AGENTS=5, MAX_TOTAL_AGENTS=10, MAX_FEATURE_RETRIES=3, PLAYWRIGHT_CLI_SESSION set for each agent, testing agents turned off by YOLO mode or a ratio of 0, and the slider in AgentControl.tsx (1–5, shown while stopped, saved per project).
• Docs only, no code changes, so I didn't run the UI.

Assumptions

• I read the issue as a question about a feature that already exists, so the fix is documentation, not new code.
• The PR comes from the fork arkaccess/autoforge, because the account has no push access to AutoForgeAI/autoforge (pushing returned 403).

Closes #5

🤖 Generated with Claude Code

[zwanski-start]

🔍 QA report: ✅ Passed

Tester: Ada (cubefarm agent, in a fresh session) · Round: 1 · Author: Dennis

Docs-only PR: adds a 'Parallel Mode (Multiple Agents)' section to README.md, which answers issue #5 (run several agents at once), and replaces CLI flags in CLAUDE.md that don't exist. Every claim was checked against the code (agent limits, retry count, per-agent browser session, initializer runs alone, regression agent range and YOLO behaviour, the UI slider), and every documented CLI command was run through the real argparse. The new flags parse and the old flags fail (exit 2). No code changed; ruff and the security tests pass, and the only pytest failures are 21 async tests in test_devserver_security.py, an untouched file, where pytest did not recognise the asyncio mark.

	Check	Details
✅	Issue #5 acceptance: document how to run multiple agents concurrently	The README has a new section under How It Works covering the UI slider, the --concurrency CLI flag, how features are claimed and dependencies handled, browser isolation, regression agents, batching, limits and trade-offs. It answers the question in the issue.
✅	README claims match the code	Checked: MAX_PARALLEL_AGENTS=5, MAX_TOTAL_AGENTS=10 and MAX_FEATURE_RETRIES=3 in parallel_orchestrator.py. PLAYWRIGHT_CLI_SESSION is set per coding and testing subprocess. _run_initializer runs as a blocking step before coding starts. testing_agent_ratio is clamped to 0-3, and YOLO mode or a ratio of 0 skips testing agents. --testing-ratio and --batch-size (default 3) exist in argparse. Concurrency is clamped to 1-5. The AgentControl.tsx range input is min 1 / max 5 with a GitBranch icon, shown only while stopped, and saved via default_concurrency in the project settings. SettingsModal has 'Regression Agents' with 0-3. AgentMissionControl shows 'Mission Control'.
✅	CLAUDE.md flag corrections are valid	Parsed the documented commands with autonomous_agent_demo.parse_args(). --concurrency 3, --concurrency 5 --yolo, --feature-ids 1,2,3, --testing-feature-ids 1,2,3, --testing-ratio 0, --batch-size 3 and --parallel 3 parse. The old --max-concurrency 3 and --batch-features 1,2,3 exit with code 2, which confirms they were wrong. The note that --parallel is a deprecated alias matches the code.
✅	Scope / regressions	git diff --name-only origin/master...HEAD lists only CLAUDE.md and README.md. No code, schema, security or UI changes.
✅	Python lint and tests	ruff is clean and both security suites pass. pytest: 144 passed, 21 failed, all in test_devserver_security.py. Those are async tests and pytest flagged pytest.mark.asyncio as unknown, which suggests pytest-asyncio is missing from the scratch venv. The file is untouched by this docs-only PR; the failures were not re-run with the plugin installed.
⏭️	UI build, lint, e2e and browser check	No UI or served-app files changed, so the build, lint, e2e and Playwright browser check would not exercise anything in this PR.

🧪 Commands run

Command	Result
git diff origin/master...HEAD	2 files changed (CLAUDE.md, README.md), +36/-8
python -c 'parse_args()' with each documented flag set (scratch venv with requirements.txt)	All 7 documented invocations parse; the old --max-concurrency and --batch-features exit 2
ruff check .	All checks passed
python test_security.py	ALL TESTS PASSED
python test_security_integration.py	ALL INTEGRATION TESTS PASSED
python -m pytest -q	144 passed, 21 failed (all in test_devserver_security.py: async tests, pytest flagged pytest.mark.asyncio as unknown; file not touched by this PR)

No browser screenshots were taken in this round.

_{Posted by cubefarm · merges automatically once GitHub's checks pass}