Cursor Codebase Visualization Guide

Give Cursor Composer and Agent a deterministic architecture lens: map real modules, inspect coupling hotspots, and export shareable offline HTML maps.

ArchRay v0.6.0 By David Yin · Updated 2026-11-20 MIT Open Source

Install ArchRay with `sh -s -- . cursor` to add `.cursor/rules/archray.mdc` and slash commands (`/archray`, `/archray-frontend`, `/archray-backend`, `/archray-data`). When triggered in a fresh Cursor Agent session, Cursor extracts verified repository facts into `.archray/graph.json` and builds a self-contained 3D/2D `.archray/index.html` viewer.

1. Install ArchRay Rules & Commands in Cursor

Running the bootstrap script with `cursor` (or `claude,cursor` if your team uses both) drops a dedicated Cursor rule file alongside isolated CLI binaries in `.archray/tool`.

Host File / FolderWhat It Provides Inside Cursor
.cursor/rules/archray.mdcAlways-available project rule guiding Cursor Agent to read real files & produce Graph v2 JSON
.cursor/commands/archray.mdSlash command entry `/archray` plus layer variants (`/archray-frontend`, `/archray-backend`, `/archray-data`)
.archray/graph.schema.jsonTypeBox JSON schema ensuring every generated node, edge, and flow is valid
Install for Cursor (or multi-host claude,cursor)
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . cursor
# Using multiple hosts in one repo:
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . claude,cursor

2. Cursor Prompts & Deterministic Slicing Workflow

Notice Cursor separates preset commands with a hyphen (`/archray-frontend`) rather than a colon, or accepts natural language requests anywhere in Agent mode because `.cursor/rules/archray.mdc` stays indexed inside the workspace.

Trigger inside Cursor Agent / Chat & re-slice locally
# Full system discovery in Cursor chat:
/archray

# Focused frontend slice in Cursor:
/archray-frontend

# Instant offline re-theme or custom cross-layer combo via terminal:
./.archray/archray build .archray/graph.json --layers frontend,gateway,data --style glass --force --no-open

3. Why Cursor Teams Pair Composer with ArchRay

During refactors or onboarding onto monorepos, raw chat summaries scroll out of context quickly. ArchRay anchors every module to real `sourcePaths` and surfaces replaceability trade-offs right beside the 3D diagram:

  • Inspect health hotspots (e.g., 6,200-LOC sync locks or hardcoded fallback secrets) visually rather than hunting across grep tabs.
  • Preview drop-in or managed service replacements and copy ready-to-paste migration prompts back into Cursor Composer.
  • Share an interactive `.archray/index.html` or unclipped 4K-class PNG in Slack/Confluence with colleagues who do not have Cursor open.

Frequently Asked Questions

Can Claude Code and Cursor share the same .archray installation?

Yes. Install with `sh -s -- . claude,cursor` (or `--agent all`). Both hosts write into `.archray/graph.json` using identical Graph v2 semantics and share `.archray/tool`.

Does ArchRay add external MCP servers or slow down Cursor indexing?

No MCP background server is needed. `.cursor/rules/archray.mdc` is lightweight Markdown and the viewer CLI only runs when building or validating `.archray/graph.json`.

What if Cursor generates English labels when I wanted bilingual zh-CN + en?

ArchRay v0.6.0 Skill explicitly asks the agent to set `meta.locales: ["zh-CN", "en"]` and translate every node, layer, edge, finding, and flow. If any entry is single-language, tell Cursor to complete bilingual translations against `.archray/graph.schema.json` and rebuild.

How do I check installation integrity inside Cursor terminal?

Run `./.archray/archray doctor` to verify Node.js 20+, schema assets, embedded vector brand icons (167 logos), and packaged viewer bundles.

Try ArchRay on your repository in 30 seconds

100% local CLI and single-file offline HTML across Claude Code, Cursor, Antigravity, Pi, and Codex.

Related Guides & Reference