Raysense

Raysense reads your repository as a graph: who imports who, where the cycles are, which files are now load-bearing, what tends to change together. It runs locally, refreshes on save, and serves the whole picture to your coding agent over MCP. Before an edit, the agent can ask what depends on this file. After a chunk of edits, it can ask did this regress anything.

Why

A coding agent reads source one file at a time. The shape of the project (its modules, its layers, its cycles, the files that always change together) never reaches its working memory. Reviewers operate on diffs, and a diff hides structure by definition. So architectural drift is invisible until it shows up as a production bug, a regression, or a refactor that takes a week.

Grading model

Six dimensions, each graded A through F against the dependency graph and commit history of the repo. The overall score, 0 to 100, is their weighted aggregate:

• Modularity - how cleanly modules separate
• Acyclicity - how much the dependency graph really is a graph
• Depth - how layered (or how flat-and-tangled) the code is
• Equality - how evenly responsibility is distributed
• Redundancy - how much logic is duplicated
• Structural uniformity - how consistent the patterns are

The score moves with structure, not with cosmetics: adding tests or shuffling files around will not lift it.

Install

One-liner. Installs the raysense binary and registers it as a stdio MCP server with whichever local Claude hosts are present (Claude Desktop and / or the claude CLI):

curl -fsSL https://raw.githubusercontent.com/RayforceDB/raysense/main/install.sh | sh

Step by step instead:

cargo install raysense   # binary only
raysense install         # register raysense with every Claude host present

The install command auto-detects every Claude host on the machine and registers raysense with each one in its native form:

| Host | Where it writes | What you get | |---|---|---| | Claude Desktop | claude_desktop_config.json | MCP server (50 tools + 6 prompts in the "+" menu) | | Claude Code | ~/.claude/settings.json (marketplace + enabledPlugins) | Plugin: tools + prompts + slash commands (/raysense:audit) + skills | | Cowork | local-agent-mode-sessions///cowork_plugins/known_marketplaces.json | Marketplace registered; finish with /plugin install raysense@raysense-marketplace in your next Cowork session |

Force a subset when you want to be explicit:

raysense install --desktop   # only Claude Desktop
raysense install --code      # only Claude Code (plugin install)
raysense install --cowork    # only Cowork (research preview)

Re-running is safe. Existing raysense entries are overwritten silently, so upgrading via cargo install raysense and then re-running raysense install points the host at the new binary in one step.

Skip the host wiring if you only want the CLI:

curl -fsSL https://raw.githubusercontent.com/RayforceDB/raysense/main/install.sh | sh -s -- --no-mcp

Update

To upgrade an existing install to the latest release:

cargo install raysense --force   # pull the newest binary from crates.io
raysense install                 # repoint every detected host at the new binary

Or in one shot via the installer (it also takes --version if you want to pin):

curl -fsSL https://raw.githubusercontent.com/RayforceDB/raysense/main/install.sh | sh

For Claude Code, after upgrading the binary also run:

/plugin uninstall raysense@raysense-marketplace
/plugin install raysense@raysense-marketplace

(or use /plugin reinstall raysense if your Claude Code version supports it, followed by /reload-plugins). This pulls the new plugin manifest, slash commands, and skills from GitHub. The MCP server picks up the new binary automatically because it's resolved from PATH on each launch.

For Cowork, run /plugin install raysense@raysense-marketplace in a fresh Cowork session (the marketplace was registered by raysense install; cowork fetches the plugin on first install).

For Claude Desktop, just quit and reopen the app — the MCP server respawns on launch and the new binary is on PATH from cargo install --force.

Agent surfaces

Once raysense is installed, agents see it through up to four surfaces. Which ones light up depends on the host:

| Surface | Invoked by | Available in | |---|---|---| | MCP tools (raysense_health, raysense_hotspots, raysense_blast_radius, …) | The model auto-calls them as needed | Desktop, Code, Cowork | | MCP prompts (templated workflows, parametrized) | Desktop "+" attachment menu / Claude Code /mcp__raysense__* | Desktop, Code, Cowork | | Plugin slash commands (/raysense:*) | User typing / | Code, Cowork | | Plugin skills (model-triggered phase workflows) | The model picks them up automatically when phase-relevant | Code, Cowork |

The six workflow names are consistent across surfaces:

| Name | What it does | Args | |---|---|---| | bootstrap | Scan, save baseline, surface top hotspots / failing rules | path | | verify | Rescan, diff against the session baseline | path | | drift | Diff over a time window (7d / 30d / 90d) | path, optional window | | impact | Blast radius + coupling + cycle exposure for one file | path, file | | query | Run a Rayfall query (select / .graph.* / Datalog) against the baseline | path, question | | audit | Heavy review: architecture, evolution, test gaps, DSM | path |

In Claude Code, type /raysense:audit /path/to/repo for the slash form, or let the model invoke the matching skill. In Claude Desktop, click the "+" attachment button next to the prompt bar, pick raysense → audit, and fill in the path. The MCP tools (50+ of them, listed in raysense --help and via tools/list) are always callable directly by the model.

Use

raysense .              # health report
raysense . --check      # CI gate, exits non-zero on rule violations
raysense . --watch      # rescan + reprint on a 2s loop
raysense . --ui         # live dashboard at http://localhost:7000
raysense --mcp          # stdio MCP server for agents

Sample output

Pointed at this very repo (raysense .):

score 82 / 100
coverage 90 / 100
structure 68 / 100
facts files=34 functions=656 calls=7518 call_edges=1383 imports=247
imports local=98 external=124 system=0 unresolved=25
graph resolved_edges=89 cycles=0 max_fan_in=53 max_fan_out=21
coupling local_edges=98 cross_module_edges=0 god_files=2 unstable_hotspots=0
size max_file_lines=5907 max_function_lines=1345 large_files=7 long_functions=20
test_gap production_files=13 test_files=0 files_without_nearby_tests=13
dimensions modularity=100/100 (A) acyclicity=100/100 (A) depth=100/100 (A)
           equality=45/100 (F) redundancy=80/100 (B) structural_uniformity=79/100 (C)
overall_grade B
architecture depth=4 max_blast_radius=7 max_blast_radius_file=src/facts.rs
complexity max=140 avg=4.261 cognitive_max=119 cognitive_avg=3.457 dead_functions=50
evolution available=true commits_sampled=151 changed_files=34 authors=2 bug_fix_commits=1

--json produces the same facts in machine-readable form for CI gates, diffs, and agent consumption. --ui brings up the same data live in the browser, --watch keeps the terminal report fresh as you edit, and --mcp exposes every fact and rule to your coding agent over MCP.

Query and policy

Every saved baseline is a queryable columnar database. Run free-form Rayfall expressions, drop in custom rules as .rfl files, and bring external CSVs into the same query substrate.

# 1. Save a baseline with 21 splayed tables (files, functions, calls,
#    call_edges, imports, types, hotspots, change_coupling,
#    trend_health, trend_hotspots, trend_violations, ...)
raysense baseline save .

# 2. Ad-hoc query in Rayfall (LISP-like, prefix, arity-strict).
raysense baseline query files \
    '(select {from: t where: (> lines 500) desc: lines})'

# 3. Graph algorithms over the call graph (PageRank, Louvain, topsort,
#    shortest-path, betweenness, k-shortest, BFS expand).
raysense baseline query call_edges \
    '(select {from: (.graph.pagerank
                      (.graph.build t (quote caller_function)
                                      (quote callee_function))
                      30 0.85)
              desc: _rank take: 10})'

# 4. CI-gated architectural rules. Drop *.rfl files in
#    .raysense/policies/; each must return a (severity, code, path,
#    message) table. Exit code 0 pass, 1 eval error, 2 error finding.
raysense policy check

# 5. Bring your own data. Coverage, lints, runtime traces,
#    pre-computed embeddings -- all join the baseline through the
#    shared sym table.
raysense baseline import-csv coverage ./coverage.csv
raysense baseline query coverage \
    '(select {from: t where: (/.raysense/`. Two sessions on two repos = two independent
baselines, zero cross-project bleed.

## Capabilities

- **Live treemap dashboard** - every file, every metric, every cycle,
  open in your browser while you work
- **Baselines and what-if** - diff against a saved snapshot; simulate
  an edit (delete a file, break a cycle) before touching the tree
- **Splayed-table agent memory** - scan results materialized as
  columnar tables so an agent's follow-up questions are instant
  reads, not re-scans
- **Rayfall query layer** - run select / `.graph.*` (PageRank,
  Louvain, topsort, shortest-path, betweenness, ...) / Datalog rules
  with transitive closure / vector primitives (cos-dist, knn,
  hnsw-build, ann) against the saved tables. Same vocabulary in
  agent queries, MCP tools, and committed `.rfl` policy packs
- **Policy packs as code-reviewable files** - `.raysense/policies/*.rfl`
  are Rayfall expressions that return a (severity, code, path,
  message) table. `raysense policy check` walks the directory and
  exits 0 / 1 / 2 for CI gating. Architectural rules ship in the
  repo, not in raysense's release notes
- **Bring your own data** - `raysense baseline import-csv` lifts any
  CSV into a queryable baseline table. Coverage data, lint counts,
  runtime traces, pre-computed embeddings -- all join the structural
  baseline through the shared sym table
- **Edit-risk per file** - one number per file ranking which the next
  agent edit is most likely to break. Composite of churn, max
  complexity, single-owner penalty, and missing-tests penalty,
  refreshed on every save
- **Drift over time** - every baseline save and `trend record`
  appends one row to the splayed `trend_health`, `trend_hotspots`,
  and `trend_violations` tables in the saved baseline. Agents query
  "what got worse over the last 30 days" through Rayfall, the typed
  `raysense_drift` MCP tool, or the `drift` skill, all reading the
  same columnar substrate as every other baseline table. No JSON
  sidecar. Verify still surfaces per-dimension regressions against
  the saved baseline (Equality B to D) for the no-time-window case
- **Bug-density per file** - files where most of the churn is fix
  commits float to the top. Conventional Commits prefixes (fix,
  hotfix, revert) drive the classifier; absolute count and ratio
  against total commits both feed the ranking
- **Test gap detection** - files without nearby tests, ranked by
  structural risk. Feeds directly into the edit-risk score so
  untested files in churn-heavy areas surface first
- **Evolution signal** - bus factor per file, change-coupling pairs,
  temporal hotspots (churn x complexity), file age windows, and
  bug-fix concentration over the last 500 commits
- **69 language profiles out of the box** - 11 languages with full
  AST analysis (Python, TypeScript, C++, Java, C#, Kotlin, Scala,
  Swift, Ruby get type inheritance on top; Rust and C stop at
  complexity since their type models don't fit the inheritance
  graph). Rayfall (the RayforceDB query language) ships with native
  function/import/type extraction tuned to its S-expression syntax.
  57 more standard profiles (Go, Elixir, Haskell, Clojure, Zig,
  GLSL, Terraform, Dockerfile, ...) via configurable plugins. Add
  your own in `.raysense/plugins/`.

## Built on Rayforce

  
    
    
    
  

The splayed-table agent memory, the baseline tables you can query
back, and the columnar storage behind the live dashboard are all
powered by **[Rayforce](https://github.com/RayforceDB/rayforce)**, an
in-memory analytics runtime optimized for graph-shaped queries.
Rayforce is what makes "ask the same question a hundred times during
a coding session" cost a hundred microseconds instead of a hundred
re-scans. It's open-source and linked statically into the raysense
binary; there is nothing extra to install.

If you're building structural-analysis tooling of your own, take a
look. Rayforce is a standalone project and useful well beyond this
one.

## Configuration

`.raysense.toml` at the repo root overrides everything: rule
thresholds, plugin language definitions, baseline scoring, what-if
ignored paths. Per-language rule overrides let one language demand
stricter caps than another. `raysense --help` lists every flag.

## Building from source

```bash
git clone https://github.com/RayforceDB/raysense.git
cd raysense
cargo build --release

The rayforce C runtime is sourced from upstream at the SHA pinned in .rayforce-version. build.rs clones it on first build, or uses a RAYFORCE_DIR=/abs/path you provide. Requires git, make, and a C compiler (clang or gcc).

License

MIT. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RayforceDB
• Source: RayforceDB/raysense
• License: MIT
• Homepage: https://sense.rayforcedb.com/

Install and usage instructions live in the source repository linked above.