Sephera is a Rust CLI for understanding codebases fast.
Count a repository, build a deterministic AI-ready context pack, trace dependency blast radius, or expose the same workflows through MCP from one binary.
Documentation: https://sephera.vercel.app
Current release line: v0.5.0 (pre-1.0).
Sephera currently focuses on four practical commands:
loc: fast, language-aware line counting across project treescontext: deterministic Markdown or JSON bundles with AST compression, focus paths, and Git diff awarenessgraph: dependency graph analysis via Tree-sitter import extractionmcp: built-in MCP server for direct AI agent integration
It is intentionally narrow in scope. Sephera does not try to be an agent runtime, a hosted service, or a provider-specific AI wrapper.
New in v0.5.0: URL mode for loc, context, and graph, including GitHub/GitLab tree URLs, remote config discovery, and MCP support.
Most codebase tools stop at one layer:
- metrics tools tell you how large a repository is
- AI helpers try to ingest too much code at once
- graph tools explain structure but not how to package it for review or prompting
Sephera connects those layers. It turns repository structure into something you can act on:
- inspect a local repo or a public repo URL without cloning first
- build a deterministic Markdown or JSON pack that fits a real token budget
- trace reverse dependencies before changing a shared module
- keep shared defaults in
.sephera.toml - expose the same workflows directly to AI agents through MCP
If you only need raw LOC, cloc and tokei already do that well. Sephera matters when you need the next step too.
cargo install sephera
sephera loc --url https://github.com/Reim-developer/Sephera
sephera context --url https://github.com/Reim-developer/Sephera/tree/master/crates/sephera_core --compress signatures --budget 32k
sephera graph --url https://github.com/Reim-developer/Sephera --what-depends-on crates/sephera_core/src/core/runtime/source.rs --depth 1
sephera mcpThose four commands cover the core use case: inspect a repo, build a focused pack, trace impact, then wire the same capabilities into an agent.
loc: fast, language-aware repository metrics with terminal table output and newline portability acrossLF,CRLF, and classicCRcontext: deterministic Markdown or JSON bundles with focus paths, Git diff awareness, token budgets, AST compression, and export-ready outputgraph: semantic dependency graph analysis with reverse dependency queries, depth filtering, cycle detection, and export to JSON, Markdown, XML, or DOTmcp: built-in MCP server exposingloc,context, andgraphover stdio for Claude Desktop, Cursor, and other MCP-compatible clients
- URL mode: analyze cloneable repo URLs plus GitHub and GitLab tree URLs directly, with
--refsupport for repo URLs - AST compression: use Tree-sitter-powered
signaturesorskeletonmodes to reduce token usage by 50-70% while preserving API shape - Review-friendly context: center packs on
HEAD~1,origin/master, or remote base refs, then keep the result deterministic and machine-readable - Dependency impact analysis: find what depends on a file, limit traversal depth, and export architecture views without switching tools
- Repo-level defaults: keep team-wide
contextsettings in.sephera.toml, then layer named profiles and CLI overrides on top - Agent integration: expose the same local engines through MCP instead of wrapping shell scripts around CLI commands
- Stability work: reproducible benchmarks, regression suites, fuzz targets, and generated built-in language metadata from
config/languages.yml
Install the published CLI from crates.io:
cargo install sepheraIf you do not want a local Rust toolchain, download a prebuilt archive from GitHub Releases. Release assets ship as zipped or tarball binaries for the mainstream desktop targets supported by the release workflow.
If you are working from source instead, see the contributor workflow in the docs.
The examples below assume a sephera binary is available on your PATH.
Count lines of code in the current repository:
sephera loc --path .Inspect a public repository directly from a URL:
sephera loc --url https://github.com/Reim-developer/SepheraBuild a focused context pack for a local repository:
sephera context --path . --focus crates/sephera_core --format json --output reports/context.jsonBuild a context pack from a remote repository tree URL:
sephera context --url https://github.com/Reim-developer/Sephera/tree/master/crates/sephera_core --format jsonCompress context excerpts to reduce token usage:
sephera context --path . --compress signatures --budget 64kBuild a review-focused pack from Git changes:
sephera context --path . --diff HEAD~1 --budget 32kThe same base-ref workflow works in URL mode:
sephera context --url https://github.com/Reim-developer/Sephera --ref master --diff HEAD~1 --budget 32kIn URL mode, context --diff accepts base refs such as main, master, HEAD~1, tags, or commit SHAs. Working-tree modes (working-tree, staged, unstaged) are intentionally rejected because remote checkouts are clean temp clones.
Analyze the dependency graph for the codebase:
sephera graph --path . --format markdown
sephera graph --path . --focus crates/sephera_core --format dotAnalyze a tagged remote repository revision:
sephera graph --url https://github.com/Reim-developer/Sephera --ref v0.5.0 --format markdownTrace reverse dependency impact before changing a file:
sephera graph --path . --what-depends-on crates/sephera_core/src/core/runtime/source.rs --depth 1Start MCP server for AI agent integration:
sephera mcpList the profiles available for the current repository:
sephera context --path . --list-profilesConfigure repo-level defaults for context:
[context]
focus = ["crates/sephera_core"]
budget = "64k"
compress = "signatures"
format = "markdown"
output = "reports/context.md"
[profiles.review.context]
diff = "origin/master"
focus = ["crates/sephera_core", "crates/sephera_cli"]
budget = "32k"
output = "reports/review.md"The configuration model is documented in more detail on the docs site, including discovery rules, precedence, path resolution, field-by-field behavior for [context], and named profiles under [profiles.<name>.context].
Sephera can compress source files using Tree-sitter to extract only structural information such as function signatures, type definitions, imports, and trait declarations while replacing implementation bodies with { ... }.
This typically reduces token usage by 50-70% without losing the API surface or architectural overview of the codebase.
Supported languages: Rust, Python, TypeScript, JavaScript, Go, Java, C++, C.
sephera context --path . --compress signatures --budget 64k
sephera context --path . --compress skeletonSephera includes a built-in MCP (Model Context Protocol) server that exposes loc, context, and graph as tools over stdio transport.
This allows AI agents such as Claude Desktop, Cursor, and other MCP-compatible clients to call Sephera directly without shell wrappers.
sephera mcpExample MCP client configuration (Claude Desktop):
{
"mcpServers": {
"sephera": {
"command": "sephera",
"args": ["mcp"]
}
}
}loc produces a fast, readable terminal summary for project trees:
Scanning: crates
╭──────────┬──────┬─────────┬───────┬─────────╮
│ Language ┆ Code ┆ Comment ┆ Empty ┆ Size │
│ ┆ ┆ ┆ ┆ (bytes) │
╞══════════╪══════╪═════════╪═══════╪═════════╡
│ Rust ┆ 9724 ┆ 652 ┆ 1357 ┆ 358209 │
│ TOML ┆ 113 ┆ 0 ┆ 11 ┆ 3493 │
│ Markdown ┆ 69 ┆ 0 ┆ 35 ┆ 2980 │
│ Totals ┆ 9906 ┆ 652 ┆ 1403 ┆ 364682 │
╰──────────┴──────┴─────────┴───────┴─────────╯
Files scanned: 88
Languages detected: 3
Elapsed: 3.909 ms (0.003909 s)
context builds a structured pack that can be exported for people or tooling:
graph builds dependency graphs with cycle detection and exports to Markdown/Mermaid:
# Dependency Graph Report
**Base path:** `crates`
## Summary
| Metric | Value |
| --------------------- | ----- |
| Files analyzed | 82 |
| Internal edges | 48 |
| External edges | 495 |
| Circular dependencies | 0 |
## Dependency Diagram
```mermaid
graph LR
n0["args.rs"]
n1["budget.rs"]
%% ... remaining edges and nodes ...mcp seamlessly hooks AI agents up to your codebase without wrappers using standard JSON-RPC over stdio:
--> { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "loc", "arguments": { "path": "crates" } } }
<-- {
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{
"type": "text",
"text": "Scanning: crates\n\n╭──────────┬──────┬─────────┬───────┬─────────╮\n│ Language ┆ Code ┆ Comment ┆ Empty ┆ Size │..."
}]
}
}The benchmark harness is Rust-only and measures the local CLI over deterministic datasets.
- Default datasets:
small,medium,large - Optional datasets:
repo,extra-large extra-largetargets roughly 2 GiB of generated source data and is intended as a manual stress benchmark
Useful commands:
python benchmarks/run.py
python benchmarks/run.py --datasets repo small medium large
python benchmarks/run.py --datasets extra-large --warmup 0 --runs 1Benchmark methodology, dataset policy, and caveats are documented in benchmarks/README.md and on the docs site.
Public documentation: https://sephera.vercel.app
Docs source lives in docs/, built as a static Astro Starlight site.
Useful local docs commands:
npm run docs:dev
npm run docs:build
npm run docs:previewcrates/sephera_cli: CLI argument parsing, command dispatch, config resolution, and output renderingcrates/sephera_core: shared analysis engine, traversal, ignore matching,loc, andcontextcrates/sephera_mcp: MCP server implementation (Model Context Protocol)crates/sephera_tools: explicit code generation and synthetic benchmark corpus generationconfig/languages.yml: editable source of truth for built-in language metadatabenchmarks/: benchmark harness, generated corpora, reports, and methodology notesdocs/: public documentation sitefuzz/: fuzz targets, seed corpora, and workflow documentation
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
npm run pyrightThis repository is distributed under the GNU General Public License v3.0. See LICENSE for the full text.
