archgraph

Endpoint-first static code graph analyzer and interactive viewer for backend/frontend architectures.

Install

npm install -g archgraph

Packages

• @archgraph/core: static analyzer, graph model, view builder, exporters
• @archgraph/cli: arcgx command for analyze/export/view/describe/install
• @archgraph/viewer: local interactive viewer server + DAG client with code drilldown and task queue

Quick Start

# Analyze a backend repo
arcgx analyze --project /path/to/your/project --out graph.json

# Export to Cypher or Mermaid
arcgx export --graph graph.json --format cypher --out graph.cypher
arcgx export --graph graph.json --format mermaid --out graph.mmd

# Generate a filtered view file
arcgx view --graph graph.json --spec view-spec.yaml --out view.json

# Launch interactive viewer
arcgx view --graph graph.json --serve --port 4310

# Generate structured bilingual descriptions for every endpoint, route_handler, and function
# Recommended: Claude Sonnet 4.6 for claude executor, GPT-5.3-Codex (medium) for codex executor
arcgx describe \
  --graph graph.json \
  --out descriptions.json \
  --executor codex \
  --executor-config .arcgx/executors.json \
  --language bilingual \
  --detail structured

Install as Codex Skill / Claude Plugin

# Install both Codex and Claude integrations
arcgx install --target all

# Codex only
arcgx install --target codex

# Claude only
arcgx install --target claude

# Custom home paths
arcgx install --target all --codex-home /path/to/.codex --claude-home /path/to/.claude

# Dry-run preview
arcgx install --target all --dry-run

Canonical Graph Format

GraphBundle { schemaVersion, createdAt, project, strings[], nodes[], edges[], groups[], indexes }

Node kinds:

• endpoint, route_handler, function, method, class, object, agent, langgraph_node, mcp_tool, module, file, ui_route, ui_component, group, condition

Edge kinds:

• declares_endpoint, handles, calls, imports, invokes_agent, uses_mcp_tool, langgraph_edge, belongs_to_group, ui_calls_api, frontend_proxies_to_backend, evaluates_condition, condition_true, condition_false, condition_case

Extraction Coverage

• Express route extraction with mounted prefix propagation
• Handler linkage from endpoint to route handlers and function symbols
• Transitive call graph extraction using TypeScript AST (with local TypeScript module fallback)
• Conditional flow extraction for if/switch/ternary branches into explicit condition nodes
• LangGraph extraction from .addNode/.addEdge/.addConditionalEdges chains
• MCP extraction from *_TOOLS arrays and callTool("...") usage
• Grouping by endpoint + secondary overlays by agent/purpose

Viewer Capabilities

• Endpoint-first directed graph rendering (logical DAG) with conditional edge styling
• Grouping by endpoint, agent, or purpose with item selector and search
• Node click opens code snippet and related 1-hop context; unrelated nodes/edges dim to 20% opacity
• Sidepanel comment/task queue with status lifecycle and approval-gated execution
• Descriptions sidebar auto-populated from arcgx describe output (auto-detected when descriptions.json sits next to graph.json)
• Filtered views re-layout nodes into a compact subgraph

arcgx describe — Node Coverage & Recommended Models

arcgx describe generates a bilingual (KO + EN) structured description for every behaviorally significant node:

| Node kind | Coverage | | --------------------------------------- | ----------------------------------------- | | endpoint | All route-level entry points | | route_handler | All handler functions wired to endpoints | | function | All functions extracted in the call graph | | agent / langgraph_node | All AI agent nodes | | condition | All conditional branch nodes | | endpoint / purpose / agent groups | Group-level aggregated summaries |

For each node, up to 12 outgoing calls, 12 condition edges, and 8 inbound callers are sampled to keep prompts focused.

Recommended models:

| Executor | Model | Notes | | -------- | ------------------------------------------- | ---------------------------------------------------------- | | claude | Claude Sonnet 4.6 (claude-sonnet-4-6) | Best structured bilingual output; fast at scale | | codex | GPT-5.3-Codex medium reasoning | Strong code comprehension; cost-efficient for large graphs |

Set the model in your executor config:

# Copy and edit the executor config template
cp docs/examples/executors.example.json .arcgx/executors.json

View Spec

See docs/view-spec.md for the full view specification format.

Tests

npm test

License

MIT