# Topology Optimizer

Topology Optimizer — a subagent that scores swarm topologies — hierarchy, mesh, ring, star, hybrid — against your workload and says which one to switch to.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 850 repo stars
- Author: ruvnet
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ruvnet/agentic-flow/tree/HEAD/.claude/agents/optimization/topology-optimizer.md
- Updated: 2026-10-26
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/topology-optimizer

## What it 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.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/topology-optimizer.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/topology-optimizer.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/topology-optimizer.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ruvnet/agentic-flow/tree/HEAD/.claude/agents/optimization/topology-optimizer.md

## When to use it
- 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
- 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

## Similar
- [agent-topology-optimizer](https://affpapa.org/en/nevibecode/skills/agent-topology-optimizer.md) — skill · ★ 189 repo stars
- [topology-mutation-and-seat-management](https://affpapa.org/en/nevibecode/skills/topology-mutation-and-seat-management.md) — skill · ★ 8928 repo stars
- [topology-and-geometry-guide](https://affpapa.org/en/nevibecode/skills/topology-and-geometry-guide.md) — skill · 1 install
- [performance-analysis](https://affpapa.org/en/nevibecode/skills/performance-analysis.md) — skill · 1200 installs
- [vault-optimizer](https://affpapa.org/en/nevibecode/agents/vault-optimizer.md) — subagent · 727 installs
- [token-optimizer](https://affpapa.org/en/nevibecode/skills/token-optimizer.md) — skill · 1100 installs

From the same set: [ruvnet/agentic-flow](https://affpapa.org/en/nevibecode/by/ruvnet/agentic-flow.md) — 76 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
