Skip to content

Home

ArchMAP

Map Your Architecture. Control Your Future.

CI PyPI Python MIT

Get started CLI reference Web UI tour

ArchMAP maps how a software project is built and tells you what is risky about it. It reads source code in 9 languages and builds a dependency graph. From that graph it finds cycles, layer violations, and fragile hotspots, and it measures how much of the project it actually understood. It also opens binaries and data files without running them, and audits secrets and AI-agent configuration.

You can use everything three ways: from the CLI (and CI), in an interactive web UI, or through an MCP server that gives AI coding agents the same answers.

pip install KG-ARCHMAP
archmap analyze .          # report + quality gates
archmap serve .            # interactive web UI on http://127.0.0.1:3000
archmap mcp .              # MCP server for Claude Code, Cursor, Windsurf

Design principles

Zero runtime dependencies (Python standard library only), so it runs on Linux, macOS, Windows, and Android/Termux. Offline and deterministic: the same input gives the same answer, with evidence. Never executes what it analyzes: code, binaries, and archives are only read.

What ArchMAP does

  • 1. Maps code architecture

    Parses Python, JavaScript, TypeScript, Rust, Go, PHP, Java, C#, and C/C++ into a file-level dependency graph, using tree-sitter when it's installed and a regex fallback per file otherwise. On top of the graph:

    • circular dependencies, with a suggested edge to break;
    • god modules, dependency explosions, and layer violations;
    • custom forbid/allow rules from .archmap.toml;
    • a 0–100 health score and a risk score and blast radius per file.

    analyze · risk · trace · diff · temporal

  • 2. Measures how far to trust it

    Every report says how much of the project made it into the graph:

    • files discovered vs. parsed;
    • parse failures, with the error;
    • files skipped for encoding or size;
    • import resolution per language.

    These combine into a confidence level (high/medium/low). When it isn't high, "no dependents" is only a lower bound.

    Analysis quality

  • 3. Guards quality in CI

    Fail a build (exit code 2) on any of:

    • cycles, layer or rule violations, god modules;
    • coupling budgets or a minimum health score;
    • import resolution or parse coverage below a threshold;
    • binary mitigations or audit findings at a chosen severity.

    SARIF export feeds GitHub Code Scanning; a reusable GitHub Action and a pre-commit hook are included.

    CI quality gates

  • 4. Gives AI agents the right context

    • A 15-tool MCP server answers what an agent would otherwise learn one file read at a time.
    • Task context returns the files to read for a task, ranked, within a token budget.
    • archmap memory gives the agent a digest at session start.
    • A Claude Code plugin and portable skill teach the agent when to call each tool.

    MCP · context · memory · Plugin

  • 5. Static reverse engineering

    Identifies 30+ formats by magic bytes and reads them without running anything:

    • ELF, PE, Mach-O, WebAssembly: linked libraries, imports/exports, mitigations (NX, PIE, RELRO, ASLR, DEP, CFG, …), packers, toolchain;
    • Data and containers: JSON, CSV, SQLite, APK/JAR/ZIP, tar.

    Plus entropy, classified strings, a hexdump, and a binary→library graph for whole folders (firmware, dist/, APK lib/).

    inspect, hexdump, strings

  • 6. Security

    • Secrets: git-aware detection; values always redacted.
    • AI-agent configuration as attack surface: unpinned or plaintext MCP servers, bypassPermissions, hooks that pipe downloads into a shell, invisible Unicode in CLAUDE.md/AGENTS.md.
    • Network exposure: open ports correlated with the code that uses them.

    audit · netscan · expose

One findings model

Every problem ArchMAP reports, from any analyzer, has the same shape: a stable id, a severity (info → critical), a confidence (0–1), a message, and evidence. The ID prefix tells you where it came from:

Prefix Domain Produced by Examples
ARCH-* code analyze circular dependency, god module, layer/rule violation
QUAL-* quality analyze parse failure, undecodable file, low import resolution
NET-* network expose open port mapped to a library the code imports, rule drift
BIN-* binary inspect executable stack, no PIE/ASLR/DEP, packed, zip-slip archive
SEC-* security audit committed AWS/GitHub/private key (redacted)
AGENT-* agent audit Bash(*) pre-approved, unpinned MCP package, risky hook

Quote the ID when discussing a finding; the evidence explains why it fired.

Web UI tour

archmap serve . opens an interactive UI in 6 languages (English, Português, Español, Français, Deutsch, 中文) that works on desktop and phones.

View What you can do
Graph Explore the dependency graph; filter by folder, cycles, or complexity heatmap; click a node for imports, dependents, and blast radius
Insights Health metrics and the analysis-confidence card (parse coverage, failures, resolution per language)
Rules & Layers Layer hierarchy, violations, and .archmap.toml rules
Trace Everything an entrypoint transitively pulls in, and what is unreachable
AI Advisor Ask an LLM (Claude, OpenAI, Ollama, any OpenAI-compatible API) for refactoring advice
Findings Every finding (ARCH, QUAL, and after an audit SEC/AGENT) filtered by domain and severity; Show in graph jumps to the file
Task context Describe a task; get the files to read in order with matching lines, and highlight them in the graph
Inspect files Inspect any file or folder in the project; the Inspector tab shows the entropy profile, a paged hexdump, filterable strings, and the binary→library graph
Security audit Run the secrets and AI-agent configuration audit
Layers / Matrix Layer diagram and dependency matrix of the most connected files

Insights view with the analysis-confidence card

Unified findings with the Inspector open

Task context highlighting the ranked files in the graph

Inventory of a folder and the binary-to-library linkage graph

Inspector with entropy profile and hexdump of a PE DLL

The server binds to 127.0.0.1 by default; endpoints that read files or change state only answer loopback requests that send JSON. See serve.

Which surface has what

Capability CLI Web UI MCP tool
Dependency graph, health, risks analyze, explain, risk Graph, Insights get_architecture_summary, get_file_context, impact_analysis
Analysis quality analyze (summary + JSON) Insights get_analysis_quality
Unified findings analyze --format json Findings list_findings
Quality gates analyze --fail-on-*, --min-* — run_checks
Reachability / dead code trace Trace trace_reachability
Architecture diff diff — diff_architecture
Task context context Task context get_relevant_context
Agent memory digest memory — get_project_memory
Reverse engineering inspect, hexdump, strings Inspect files + Inspector inspect_path, hexdump, extract_strings
Secrets & agent config audit Security audit audit_project
Network exposure netscan, expose — get_network_exposure
LLM advice advise AI Advisor —

Getting started

archmap CLI

  1. Installation: PyPI, Docker, the optional tree-sitter extra, Termux
  2. Quick Start: analyze and serve your first project
  3. AI agent plugin: one command to give Claude Code, Cursor, or Codex the ArchMAP tools
  4. Live Demo

CLI reference

Command Purpose
analyze Full report, analysis quality, quality gates, Mermaid/JSON/Cytoscape/SARIF
explain Human-readable architecture summary
risk Blast radius and risk score for a file
improve Structural suggestions + refactor script
serve Interactive web UI (graph, insights, findings, context, inspect, audit, …)
diff Compare git refs or JSON snapshots
trace BFS reachability from any entrypoint
init Generate .archmap.toml from a real dependency graph
advise LLM-powered architectural advisor
temporal Temporal coupling via git history
context Files to read for a task, packed into a token budget
inspect Static reverse engineering of files and folders
hexdump Hex + ASCII dump of a byte range
strings ASCII/UTF-16 strings, optionally only the interesting ones
audit Secrets, cross-file data flow (taint), insecure code patterns, and risky AI-agent configuration
mcp MCP server for AI assistants (15 tools)
memory Persistent architecture digest for AI coding agents
commands Machine-readable catalog of every command and option
watch Continuous analysis on file change
netscan Network host discovery + port scanning, nmap-style
expose Correlate open network ports/services with the dependency graph

What's new

  • 1.4.2: GitHub Action fixed — it installed an unrelated archmap package from PyPI instead of KG-ARCHMAP, and the sarif and fail-on-explosions inputs crashed the run; Python 3.14 supported (CI, Docker image on python:3.14-slim); express 5.3 / body-parser 2.4 (GHSA-27r3-jxmh-p828); release workflows now reject a tag that does not match the package version.
  • 1.4.1: security and accuracy review from a field test on real repositories — interprocedural taint analysis (TAINT-*) across files for Python, JS/TS, C# and Java; CWE-tagged insecure-code checks (CODE-*); SARIF export for audit; context-aware secret ranking; precise C# using resolution (no more namespace cliques); NestJS/Angular dotted imports (x.service) resolved; vendored code excluded from risk ranking; --no-cache fixed.
  • 1.4.0: static reverse engineering (inspect, hexdump, strings), analysis-quality metrics with QUAL-* findings and CI gates, audit for secrets and AI-agent configuration, context for task-scoped file ranking, seven new MCP tools, a Claude Code plugin, and five new web UI views (Findings, Task context, Inspect + Inspector, Security audit, analysis confidence).
  • 1.3.0: unified findings model (ARCH-*, NET-*) with stable IDs, severity, confidence, and evidence.
  • 1.2.0: archmap memory, a persistent markdown digest of the project's architecture for AI coding agents to read at session start.
  • 1.1.x: archmap netscan and archmap expose, nmap-style network discovery correlated with the dependency graph, with confidence scoring and [network.rules] drift detection.

See the full Changelog and Roadmap.

Governance and release

Attribution

Original distributor: Kaua Gabriel / Kauã Gabriel (Kaua-KGzin). See Original Distribution Notice and the MIT License.