Sephera
Sephera
Section titled “Sephera”Sephera is a Rust CLI for change safety: if I change this file, what else breaks? It builds a dependency graph from real imports across six languages (Rust, Python, TypeScript/JavaScript, Go, Java, C/C++), then answers that question at file and symbol level - offline, static analysis only.
The current docs describe the 2.0.x release line. Version 2.0.0 ships 24 commands:
- Change safety:
breaking,review,merge,behavior,diff,simulate,archaeology,why,impact,graph - Test analysis:
untested,affected-tests,test-priority - Code health:
dead,coupling,risk - For agents:
mcp(21 tools),skill,context,schema-impact,guard,watch - Foundations:
loc,symbols
The project is intentionally narrow in scope. It does not try to be an AI agent framework or a hosted service. The goal is to provide reliable local analysis primitives that fit naturally into review, debugging, and prompting workflows.
Why it exists
Section titled “Why it exists”Modern code workflows need two kinds of signals:
- trustworthy repository metrics
- focused context bundles that are small enough to fit inside real prompt budgets
Sephera provides both without requiring a server, a browser extension, or a provider-specific integration.
Current capabilities
Section titled “Current capabilities”- Fast
locanalysis with per-language totals in table, Markdown, JSON, and CSV - Declaration counts per language read from Tree-sitter parse trees, so a keyword inside a comment or a string is not counted
- Deterministic
contextpacks with focus-path and focus-symbol prioritization, Git diff awareness, and approximate token budgeting - Tree-sitter AST compression that keeps the API surface and drops function bodies, typically 50-70% fewer tokens on implementation-heavy files
- Dependency
graphgeneration with cycle detection and exports to Markdown, JSON, XML, and DOT impactblast-radius reports for a single file or for every file a change touched- CI gates via
--fail-on,--fail-on-cycles, and--fail-on-unresolved, exiting 2 on a violated rule and 1 on a broken run watchto re-run any analysis on every file change, with write debouncing- Built-in MCP server for direct integration with AI agents like Claude Desktop
- URL mode for direct analysis of cloneable repo URLs and GitHub/GitLab tree URLs
- Repo-level defaults through
.sephera.toml, with[project]shared by every command plus per-command tables, named profiles, and aliases - Export to Markdown for human copy-paste workflows and JSON for automation
- Generated language metadata sourced from
config/languages.yml - Byte-oriented scanning with newline portability across
LF,CRLF, and classicCR - Benchmark and fuzzing infrastructure to keep behavior stable over time
breakingreports symbols removed or reshaped between two refs, joined to the files that still use themreviewreports blast radius and affected tests for each file a change touchesmergepredicts merges git completes cleanly but that break the buildbehaviorcatches silent changes that still compile (argument order, constants)diffis a symbol changelog;simulatetries a rename/move without touching the tree;archaeologytraces a symbol through history- FFI impact: a Rust
#[pyfunction]change shows which Python files call it (also JNI, wasm-bindgen, cgo) test-priorityorders tests by what changed;schema-impactreports the impact of a database schema change;skillinstalls the change-safety agent skill
Quick examples
Section titled “Quick examples”These examples assume sephera is installed and available on your PATH.
Count lines of code in the current repository:
sephera loc --path .Analyze a remote repository directly:
sephera loc --url https://github.com/Reim-developer/SepheraBuild a focused context pack and export it to JSON:
sephera context --path . --focus crates/sephera_core --format json --output reports/context.jsonCompress context excerpts to reduce LLM token usage:
sephera context --path . --compress signaturesStart the MCP server to let AI agents call Sephera directly:
sephera mcpBuild a review pack from recent Git changes:
sephera context --path . --diff HEAD~1 --budget 32kRun the same review flow on a remote checkout:
sephera context --url https://github.com/Reim-developer/Sephera --ref master --diff HEAD~1 --budget 32kList configured profiles for the current repository:
sephera context --path . --list-profilesTerminal demos
Section titled “Terminal demos”sephera loc
language-aware repository totals
sephera context
deterministic context bundles for people, tools, and Git review flows
sephera graph
reverse dependency queries — what breaks if you change this file
The demos above are illustrative captures of the CLI workflows described throughout the docs.
Where to go next
Section titled “Where to go next”- Start with Getting Started
- Learn the loc command
- Learn the context command
- Learn the graph command
- Learn the mcp command
- Configure repo-level defaults with .sephera.toml