arcade-agent is a framework-agnostic tool library for software architecture analysis. It provides composable tools for parsing source code, recovering architecture, detecting smells, computing metrics, and comparing versions. Tools work standalone or plug into MCP/LangChain/Claude SDK.
# Setup (Python 3.12+; run from the repo root)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,languages,mcp]" # CI installs these extras; without
# [languages] the parser tests skip
# Run tests
pytest
# Lint (CI-gated)
ruff check src/ tests/
# Type check (NOT CI-gated; many pre-existing strict errors)
mypy src/
# Example usage
python examples/basic_analysis.py /path/to/java/projectTool library with registry pattern. Each tool is independently callable; there is no CLI orchestrator. An optional analyze convenience tool composes the common ingest → parse → recover → smells → metrics path for agents/MCP (async wrapper around sequential sync stages), without replacing the composable tools.
registry.py # @tool decorator, discovery
parsers/ # Language-agnostic parsing (tree-sitter)
models/ # Shared dataclasses (DependencyGraph, Architecture, etc.)
tools/ # composable tools (ingest, parse, recover, detect_smells, summarize, analyze, api_surface, diff_impact, context_for_task, ...)
algorithms/ # Pure algorithm implementations (clustering, SCC, metrics)
exporters/ # Output format adapters (HTML, DOT, JSON, RSF, Mermaid)
adapters/ # Framework integration (MCP stub for v2)
All @dataclass in models/:
Entity— FQN, kind, package, file path, language, imports, inheritanceEdge— source FQN, target FQN, relation typeDependencyGraph— entities dict, edges list, packages dictComponent— name, responsibility, entity FQNsArchitecture— components list, rationale, algorithm used, metadataSmellInstance— smell type, severity, affected components, description, explanation, suggestionMetricResult— metric name, value, details dict
from arcade_agent import list_tools, get_tool
# Discover all tools
for t in list_tools():
print(t.name, t.description)
# Call a tool directly
from arcade_agent.tools.parse import parse
graph = parse("/path/to/project", language="java")tree-sitter+ language grammars for parsingnetworkxfor graph algorithms (SCC, clustering)scipyfor Hungarian algorithm (cluster matching)numpyfor numerical metric computationsjinja2for HTML report templatinggitpythonfor repo ingestion
- Python 3.12+ — PEP 585:
list[str],str | None - Type hints on all functions and return types
- @dataclass for domain objects
- Naming:
snake_casefunctions,PascalCaseclasses,UPPER_SNAKE_CASEconstants,_underscoreprivate - Docstrings: Google style with Args/Returns
- Imports: stdlib → third-party → local (
from arcade_agent.models.graph import ...) - Linting: ruff, mypy strict mode
- Testing: pytest, fixtures in
tests/fixtures/