Raysense

A structural X-ray for the codebases AI agents are writing.

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

cargo install raysense

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

Agent integration

Raysense ships as a Claude Code plugin:

/plugin marketplace add RayforceDB/raysense
/plugin install raysense

Four phase-scoped skills: scan + baseline at session start, blast radius before edits, regression diff after, on-demand architecture audits. Multi-codebase isolation is cwd-driven, so per-project state stays in <repo>/.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
• 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
• Score drift per session - every baseline save appends a sample; verify diffs against the previous one and surfaces per-dimension drift (Equality went B to D) instead of a single aggregate delta
• 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, 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

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.