raysense / site

# Raysense

> Raysense is an open-source Rust CLI and MCP server that scores the architectural health of a code repository. It measures six structural dimensions (Modularity, Acyclicity, Depth, Equality, Redundancy, Uniformity), grades each A through F, and aggregates them into a single 0-to-100 number. The score is published to CI as a pass/fail gate, rendered as a live treemap dashboard in the browser, and exposed to AI coding agents over a stdio MCP server so the agent can read structural state before and after each edit.

Raysense is built for AI-edited repositories. When agents commit dozens of changes per hour, per-diff code review cannot track whether the codebase shape is improving or degrading. Raysense closes that gap with a continuous structural signal.

## Key facts

- Install: `cargo install raysense && raysense install` (binary on crates.io; `raysense install` registers raysense across every Claude host on the machine)
- One-liner: `curl -fsSL https://raw.githubusercontent.com/RayforceDB/raysense/main/install.sh | sh`
- Update: `cargo install raysense --force && raysense install` (re-runs are idempotent; existing entries are silently overwritten)
- License: MIT
- Author: Anton Kundenko
- Source: https://github.com/RayforceDB/raysense
- Languages: 69 supported (11 tree-sitter built-ins with full AST analysis - Python, TypeScript, C++, Java, C#, Kotlin, Scala, Swift, Ruby, C, Rust - plus Rayfall via native S-expression extraction; 57 more via configurable prefix-pattern plugins)
- Hosts auto-installed by `raysense install`: Claude Desktop (MCP server in claude_desktop_config.json), Claude Code (raysense plugin in ~/.claude/settings.json - tools + prompts + slash commands `/raysense:*` + skills), Cowork (marketplace registered; finish in-session with `/plugin install raysense@raysense-marketplace`)
- Manual Claude Code plugin install: `/plugin marketplace add RayforceDB/raysense` then `/plugin install raysense`

## Six graded dimensions

- Modularity (A): how cleanly module boundaries separate concerns, based on the dependency graph.
- Acyclicity (B): the degree to which the dependency graph is acyclic. Cycles reduce the score.
- Depth (C): whether the codebase has appropriate layering. Both flat-and-tangled and excessively deep architectures are penalised.
- Equality (D): how evenly responsibility is distributed across files and modules.
- Redundancy (E): how much logic is duplicated.
- Uniformity (F): how consistent structural and naming patterns are.

The aggregate score moves with structural changes only. Cosmetic changes (comments, renames) do not affect it.

## CLI usage

```
cargo install raysense

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

## Agent integration

Raysense ships as a Claude Code / Cowork plugin and a stdio MCP server. `raysense install` (no flags) registers raysense with every Claude host detected on the machine. The plugin gives the agent six edit-loop workflows, surfaced four ways depending on the host:

| Surface | Invoked by | Available in |
|---|---|---|
| MCP tools (`raysense_health`, `raysense_blast_radius`, ...) | Model auto-calls | Desktop, Code, Cowork |
| MCP prompts (templated workflows with parameters) | Desktop "+" attachment menu / Code `/mcp__raysense__*` | Desktop, Code, Cowork |
| Plugin slash commands (`/raysense:*`) | User typing `/` | Code, Cowork |
| Plugin skills (model-triggered phase workflows) | Model picks up automatically | Code, Cowork |

The six workflows:

1. Bootstrap. At session start: scan, save baseline, materialise scan results as splayed-table memory.
2. Impact. Before non-trivial edits: blast radius, coupling, cycle exposure.
3. Verify. After edits: rescan, rule check, baseline diff.
4. Drift. Periodically (daily, weekly, pre-PR): compare the latest scan to the trend history across a configurable window (7d, 30d, 90d). Returns dimensions that worsened, files newly hot, and rules newly tripped.
5. Audit. On request: architecture, DSM, evolution signals, test gaps.
6. Query. Anytime: ad-hoc Rayfall expressions over the saved baseline (filter, project, aggregate, graph algorithms, Datalog rules with transitive closure).

Project state lives in `<repo>/.raysense/`, never in a global registry. Two concurrent sessions on two different repos are strictly independent.

## Query and policy

Every saved baseline is a queryable columnar database. Two surfaces share one substrate:

- Ad-hoc query: `raysense_baseline_query` (MCP) or `raysense baseline query <table> <expr>` (CLI). Three modes - select queries for filter/project/aggregate, `.graph.*` algorithms (PageRank, Louvain, topsort, shortest-path, betweenness, closeness, k-shortest, MST, BFS/DFS expand) for centrality and reachability, Datalog rules with transitive closure for declarative reachability.
- Pinned policy: drop a `.rfl` file in `<repo>/.raysense/policies/` and `raysense policy check` (or the `raysense_policy_check` MCP tool) walks the directory, evaluates each policy, and reports findings using the same RuleFinding envelope as built-in rules. Exit code 0 for pass, 1 if any policy failed to evaluate, 2 if any error-severity finding. Architectural rules ship as code-reviewable files alongside the codebase they govern - no vendored YAML schema, no plugin SDK to learn.

A policy is just a Rayfall expression that returns a table with columns severity, code, path, message. Empty result table = policy passed.

## Bring your own data

Drop a CSV; it joins the baseline.  `raysense baseline import-csv <name> <path>` (CLI) or `raysense_baseline_import_csv` (MCP) reads the CSV with first-row headers, infers column types, and writes it as a splayed table alongside the built-in ones.  Subsequent queries can join across imported and built-in tables because they share the baseline's interned-string sym table - `path` in an imported coverage CSV points to the same sym ID as `path` in the structural `files` table.

Vector primitives are built into Rayfall:
- `cos-dist` / `l2-dist` / `inner-prod` / `norm` for direct similarity.
- `knn` for brute-force nearest-neighbor over a list of candidate vectors; returns a (_rowid, _dist) table sorted ascending.
- `hnsw-build` / `ann` / `hnsw-save` / `hnsw-load` / `hnsw-info` for sub-linear approximate-nearest-neighbor on >10k vector spaces.

Pair the two: import an embeddings CSV (file_id + e0..eN columns), build an HNSW index, and ship a `.rfl` policy that flags near-duplicate functions or finds the most-similar files to a target.  Vector search becomes a CI gate without a separate service.

## Live progress

Long Rayfall queries (group-by aggregations, pivots) emit throttled progress lines on stderr from the CLI surfaces - `[rayfall] op / phase  rows_done / rows_total  elapsed=Xs  mem=YMB`.  JSON callers (--json, MCP, pipes) stay byte-clean.  Quick queries under 200ms emit nothing.

## Capabilities beyond the score

- Live treemap dashboard. Every file, every metric, every cycle, refreshed on save.
- Baselines and what-if. Diff against a saved snapshot. Simulate an edit before touching the working tree.
- Splayed-table agent memory. Scan results as columnar tables. Follow-up queries are instant reads, not re-scans.
- Test gap detection. Files without nearby tests, ranked by structural risk.
- Evolution signal. Bus factor, change-coupling pairs, temporal hotspots (churn x complexity), file age windows.

## Built on Rayforce

The agent memory, baseline tables, and live dashboard storage are powered by Rayforce (https://github.com/RayforceDB/rayforce), an open-source in-memory analytics runtime optimised for graph-shaped queries. Linked statically. Nothing extra to install.

## Optional

- Site: https://sense.rayforcedb.com/
- Repository: https://github.com/RayforceDB/raysense
- Crate: https://crates.io/crates/raysense
- Sister project: https://github.com/RayforceDB/rayforce
- About the maintainer: https://sense.rayforcedb.com/about/
- Comparison vs alternatives: https://sense.rayforcedb.com/compare/