Topology Optimizer — Claude Code subagent: what it does
Topology Optimizer — a subagent that scores swarm topologies — hierarchy, mesh, ring, star, hybrid — against your workload and says which one to switch to.
no license ★ 850 updated 2026-10-26
.claude/agents/topology-optimizer.mdWhat Topology Optimizer does
Give it a running swarm and a workload profile. It reads the layout you have now, builds candidate topologies, scores each one and comes back with a pick plus a migration plan and a downtime estimate. Candidates include hybrids and layouts the model proposes on its own.
Three parts do the work. One handles topology choice: analysis of the current state, candidate generation, multi-objective selection, migration planning. Another hunts latency: where agents sit, routing tables, caching, compression. A third searches for good agent placement with several algorithms at once — genetic, simulated annealing, particle swarm, graph partitioning, machine learning — and merges the strongest results.
It needs something to measure. With no existing swarm topology and no workload profile there is nothing to compare, and a small gain gets you an empty answer. The improvement threshold comes from constraints, and the fallback is 0.1.
What it helps with
- Pick a topology that holds up under a new workload
- Compare mesh against hierarchy before switching
- Get a migration plan with a downtime estimate
- Find slow routes and stale caches between agents
- Run several placement algorithms and keep the best mix
Example prompts for the agent
- Use Topology Optimizer on my swarm: is mesh better than ring for this workload?
- Check agent placement and give me a migration plan with minimal downtime
- Optimize latency across the messaging patterns and tell me what to change first
How to install Topology Optimizer
Manually: put the files in place
.claude/agents/topology-optimizer.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/topology-optimizer.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/topology-optimizer.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about Topology Optimizer
How do I install Topology Optimizer in Claude Code?
Put the subagent file at .claude/agents/topology-optimizer.md in your project. That is the whole step.
What does Topology Optimizer do?
It analyzes the swarm topology, generates alternatives and picks the best one for your workload across several metrics. The answer carries the recommendation, the expected gain and a migration plan.
What does it need to run?
A live swarm with its current topology and a workload profile. Pass limits through constraints, including the improvement threshold below which no switch is suggested.