Before anyone can plan a refactor, somebody has to say what the components are — and the diagram in the wiki is three years old. arcade-agent rebuilds the component structure from the source itself, flags the smells in it, and puts numbers on the result so the same measurement can be repeated after the change.
Five algorithms: pkg (package structure, the default baseline), wca and acdc (clustering), plus arc and limbo, which are LLM-powered. Running more than one is the point — recovery results disagree, and the disagreement is informative.
Four types: dependency cycle, concern overload, scattered parasitic functionality, link/upstream overload. Cycles and link overload are always algorithmic; the other two run heuristically, or through an LLM with use_llm=True.
Six decay metrics from the ARCADE lineage — RCI, TurboMQ, BasicMQ, IntraConnectivity, InterConnectivity and TwoWayPairRatio — computed over the recovered architecture, so you can run them again after the refactor.
You don't need an agent in the loop for this one. The arcade-self-analysis console script runs the whole pipeline over a source tree and writes both a JSON result and a standalone HTML report:
$ pip install "arcade-agent[languages]"
$ arcade-self-analysis --source . --algorithm pkg \
--output-json arcade_analysis_results.json \
--output-html arcade_analysis_report.htmlLanguage is auto-detected unless you pass --language. Java and Python parse from the base install; C, TypeScript, Go, Kotlin and Rust need the languages extra, as above. The report published at /self/ is this exact command run against arcade-agent's own repository, unedited.
Recovery gives you the map; these tools are how you read it:
summarize — first orientation pass over the repo, or one package at a time via focus: structure, dependency hotspots, entry points.explain_component — one component in depth: responsibility, member entities, public API surface, dependencies, cohesion.query — the specific follow-up: component_of, dependencies, dependents, most_coupled, largest, summary.dependency_cone — before extracting a module, the transitive reach in both directions, so the extraction cost is a number rather than a hunch.visualize — a shareable artifact of the run: HTML, DOT, JSON, RSF or Mermaid, for the design doc your teammates will actually read.Then re-run the same recovery after the refactor and compare the two architectures with compare, or commit the first run as a baseline and let CI diff every pull request against it.
Read recovery as evidence, not verdict. A recovered architecture is one algorithm's clustering of a statically parsed graph — pkg just reflects your package layout, and the clustering algorithms will each draw the boundaries somewhere else. Compare a couple of runs before you rewrite anything.
The parsers are structural: entities and reference edges such as imports and inheritance. Dynamic dispatch, reflection and runtime wiring don't show up as edges, which is exactly where a recovered graph looks thinner than reality.
arcade-agent's own repo runs this pipeline with --filter-non-architectural-helpers, which drops private Python helpers and @tool/@register_parser registration-import edges before recovery — a reminder that what you exclude shapes the picture as much as what you cluster.
Architecture recovery explains what the algorithms are doing; smells & metrics covers the catalogue in plain language; the metrics reference has the formulas as implemented, with worked examples from the self-analysis run. The research page traces each algorithm back to the paper it came from.
pip install "arcade-agent[languages,mcp]", point your MCP client at arcade-mcp, and run the first analysis — the getting-started page walks a real captured transcript end to end.