Skip to content
arcade-agent

Getting started

Install

Section titled “Install”
Terminal window
pip install arcade-agent

or, if you use uv:

Terminal window
uv tool install arcade-agent

Requires Python 3.12 or later. Java and Python parsing work out of the box; C, TypeScript, Go, and Kotlin need the languages extra:

Terminal window
pip install "arcade-agent[languages]"

Running the MCP server (next section) needs the mcp extra too — pip install "arcade-agent[mcp]", or just install both: pip install "arcade-agent[languages,mcp]".

Connect your agent

Section titled “Connect your agent”

arcade-agent ships an MCP server, started with the arcade-mcp console script, over stdio. Add it to your agent’s MCP config — for Claude Code, that’s .mcp.json in your project root:

{
  "mcpServers": {
    "arcade-agent": {
      "command": "uvx",
      "args": ["--from", "arcade-agent[mcp]", "arcade-mcp"]
    }
  }
}

uvx fetches the package on first launch, so there’s nothing to pre-install or keep updated. The server exposes 18 tools — the four task-shaped ones (context_for_task, diff_impact, api_surface, dependency_cone) plus the full ingest → recover → analyze pipeline. See Agent tools for the complete list.

First analysis

Section titled “First analysis”

Here’s an actual transcript — an agent pointed at pallets/click (cloned shallow), calling the MCP tools in order. Every JSON block below is real tool output, captured once against that repo; long lists are trimmed with … and noted where they are.

recover needs a parsed dependency graph, not the raw ingest result, so the real chain is ingest → parse → recover → summarize:

→ ingest(source="click-repo", language="python")
{
  "session_id": "81d5ea3beffe",
  "type": "IngestedRepo",
  "num_files": 17,
  "language": "python",
  "name": "click-repo",
  "version": "HEAD"
}

ingest also accepts a git URL directly (source="https://github.com/pallets/click") and clones it to a temp dir — a local path is used here only because the repo was already on disk.

→ parse(source_path="click-repo/src", language="python")
{
  "session_id": "ed353c7552ae",
  "type": "DependencyGraph",
  "num_entities": 572,
  "num_edges": 29,
  "num_packages": 2
}
→ recover(dep_graph="ed353c7552ae", algorithm="pkg", pkg_depth=1)
{
  "session_id": "59d3821538ef",
  "type": "Architecture",
  "num_components": 17,
  "components": [
    { "name": "Default", "num_entities": 1 },
    { "name": "Compat", "num_entities": 46 },
    { "name": "TermuiImpl", "num_entities": 35 },
    { "name": "Core", "num_entities": 141 },
    { "name": "Types", "num_entities": 93 }
    // … 12 more components, one per source module
  ],
  "algorithm": "pkg"
}

algorithm defaults to "pkg" (package-based, deterministic); the other options are wca, acdc, arc, and limbo — see Agent tools for what each one does. pkg_depth=1 groups by module here because click’s own package structure is flat; without it, pkg falls back to one component per top-level entity, which is rarely what you want on a single-package repo.

→ summarize(source_path="click-repo/src", language="python")
{
  "project": "src",
  "language": "python",
  "num_entities": 572,
  "num_edges": 29,
  "num_packages": 2,
  "entity_kinds": { "class": 82, "function": 126, "method": 364 },
  "hotspots": [
    { "fqn": "click.exceptions.UsageError", "kind": "class", "in_degree": 6, "out_degree": 1, "total_connections": 7 },
    { "fqn": "click.shell_completion.ShellComplete", "kind": "class", "in_degree": 4, "out_degree": 0, "total_connections": 4 }
    // … 8 more hotspots
  ],
  "entry_points": [
    { "fqn": "click.core.Command.main", "kind": "method", "file_path": "click/core.py" },
    { "fqn": "click.testing._FDCapture.start", "kind": "method", "file_path": "click/testing.py" }
  ]
}

Session IDs (81d5ea3beffe, ed353c7552ae, 59d3821538ef) are handles into an in-process session store — pass them straight into the next tool call instead of re-serializing the whole graph or architecture each time. They don’t survive a server restart.

What next

Section titled “What next”
  • Agent tools — all 18 MCP tools, parameters, and return shapes.
  • CI — catch architecture drift on every pull request with arcade-self-analysis and arcade-arch-diff.