[Feature] Parallel Worktree Agent Orchestration (nanocoder swarm)

[akramcodez]

Description

Add a swarm mode (and corresponding --swarm CLI flag) that allows Nanocoder to decompose a high-level goal into N parallel sub-tasks, execute each in an isolated Git worktree, and merge results back into a single unified diff presented to the user.

Today, Nanocoder operates as a single serial agent. Every major alternative - Claude Code (Agent Teams), OpenCode (multi-session) - now offers some form of parallelism behind paid or proprietary walls. This feature would make Nanocoder the only fully open-source CLI agent with native parallel worktree orchestration.

Use Case

• A developer wants to simultaneously: (a) write the implementation, (b) write unit tests, and (c) update documentation for a new feature — without waiting for each step to complete serially.
• A team runs a nightly autonomous sweep across a monorepo where different agents refactor different packages in parallel.
• A solo developer wants to explore two competing implementation approaches side by side and pick the better one.

Currently, the only workaround is manually opening multiple terminal sessions and coordinating them by hand — a fragile and slow process.

Proposed Solution

1. Decomposition Phase - reuse the existing plan mode as a structured decomposer. The coordinator agent reads the task and emits a manifest of N subtasks with file scope declarations (preventing cross-task conflicts).
2. Worktree Isolation - for each subtask, spin up a git worktree add in a temporary branch. Each worker agent operates exclusively within its worktree.
3. Worker Execution - workers are spawned as child processes via the existing source/daemon/ infrastructure, each running a full Nanocoder agent in non-interactive mode.
4. TUI Dashboard - a shared live view shows each worker's status, current tool call, and token usage. Workers report to a central message bus.
5. Merge Phase - once all workers complete, the coordinator agent receives each worker's diff, resolves conflicts (or surfaces them for human review), and presents a unified patch.
6. Trust Levels - --swarm-mode review (show diffs, no auto-apply), --swarm-mode apply (apply with confirmation), --swarm-mode yolo (auto-apply, mirrors existing YOLO mode).

# Example usage
nanocoder swarm "add OAuth2 support: implement handler, write tests, update docs"
nanocoder swarm --workers 4 --swarm-mode review "refactor the tools/ directory"

Alternatives Considered

• Manual tmux sessions - viable but entirely manual, no coordination, no merge step, not accessible to most users.
• Sequential subagent delegation - already partially covered by source/subagents/. This is an incremental approach but does not provide true parallelism or the time savings that make swarm valuable.
• External orchestration frameworks (LangGraph, CrewAI) - these are Python-ecosystem solutions that break Nanocoder's self-contained TypeScript architecture and require users to manage external dependencies. Not aligned with the local-first, zero-dependency-overhead philosophy.

Additional Context

• I have searched existing issues to ensure this is not a duplicate
• This feature aligns with the project's goals (local-first AI assistance)

Related issues: #771 (subagent delegation scoping), #787 (MCP stability - needed for multi-agent MCP use)