Sephera

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 trees
context: deterministic Markdown or JSON bundles with AST compression, focus paths, and Git diff awareness
graph: dependency graph analysis via Tree-sitter import extraction
mcp: 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.

Why Sephera

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.

Try Sephera

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 mcp

Those four commands cover the core use case: inspect a repo, build a focused pack, trace impact, then wire the same capabilities into an agent.

What Sephera Does

loc: fast, language-aware repository metrics with terminal table output and newline portability across LF, CRLF, and classic CR
context: deterministic Markdown or JSON bundles with focus paths, Git diff awareness, token budgets, AST compression, and export-ready output
graph: semantic dependency graph analysis with reverse dependency queries, depth filtering, cycle detection, and export to JSON, Markdown, XML, or DOT
mcp: built-in MCP server exposing loc, context, and graph over stdio for Claude Desktop, Cursor, and other MCP-compatible clients

Feature Highlights

URL mode: analyze cloneable repo URLs plus GitHub and GitLab tree URLs directly, with --ref support for repo URLs
AST compression: use Tree-sitter-powered signatures or skeleton modes 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 context settings 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

Install the published CLI from crates.io:

cargo install sephera

If 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.

Quick Start

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/Sephera

Build a focused context pack for a local repository:

sephera context --path . --focus crates/sephera_core --format json --output reports/context.json

Build a context pack from a remote repository tree URL:

sephera context --url https://github.com/Reim-developer/Sephera/tree/master/crates/sephera_core --format json

Compress context excerpts to reduce token usage:

sephera context --path . --compress signatures --budget 64k

Build a review-focused pack from Git changes:

sephera context --path . --diff HEAD~1 --budget 32k

The same base-ref workflow works in URL mode:

sephera context --url https://github.com/Reim-developer/Sephera --ref master --diff HEAD~1 --budget 32k

In 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 dot

Analyze a tagged remote repository revision:

sephera graph --url https://github.com/Reim-developer/Sephera --ref v0.5.0 --format markdown

Trace reverse dependency impact before changing a file:

sephera graph --path . --what-depends-on crates/sephera_core/src/core/runtime/source.rs --depth 1

Start MCP server for AI agent integration:

sephera mcp

List the profiles available for the current repository:

sephera context --path . --list-profiles

Configure 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].

AST Compression

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 skeleton

MCP Server

Sephera 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 mcp

Example MCP client configuration (Claude Desktop):

{
  "mcpServers": {
    "sephera": {
      "command": "sephera",
      "args": ["mcp"]
    }
  }
}

Terminal Demos

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
graph LR
    n0[&quot;args.rs&quot;]
    n1[&quot;budget.rs&quot;]
    %% ... remaining edges and nodes ...
</code></pre>
<p><code>mcp</code> seamlessly hooks AI agents up to your codebase without wrappers using standard JSON-RPC over <code>stdio</code>:</p>
<pre><code class="language-json">--&gt; { &quot;jsonrpc&quot;: &quot;2.0&quot;, &quot;id&quot;: 1, &quot;method&quot;: &quot;tools/call&quot;, &quot;params&quot;: { &quot;name&quot;: &quot;loc&quot;, &quot;arguments&quot;: { &quot;path&quot;: &quot;crates&quot; } } }

&lt;-- {
      &quot;jsonrpc&quot;: &quot;2.0&quot;,
      &quot;id&quot;: 1,
      &quot;result&quot;: {
        &quot;content&quot;: [{
          &quot;type&quot;: &quot;text&quot;,
          &quot;text&quot;: &quot;Scanning: crates\n\n╭──────────┬──────┬─────────┬───────┬─────────╮\n│ Language ┆ Code ┆ Comment ┆ Empty ┆    Size │...&quot;
        }]
      }
    }
</code></pre>
<h2>Benchmarks</h2>
<p>The benchmark harness is Rust-only and measures the local CLI over deterministic datasets.</p>
<ul>
<li>Default datasets: <code>small</code>, <code>medium</code>, <code>large</code></li>
<li>Optional datasets: <code>repo</code>, <code>extra-large</code></li>
<li><code>extra-large</code> targets roughly 2 GiB of generated source data and is intended as a manual stress benchmark</li>
</ul>
<p>Useful commands:</p>
<pre><code class="language-bash">python benchmarks/run.py
python benchmarks/run.py --datasets repo small medium large
python benchmarks/run.py --datasets extra-large --warmup 0 --runs 1
</code></pre>
<p>Benchmark methodology, dataset policy, and caveats are documented in <a href="benchmarks/README.md"><code>benchmarks/README.md</code></a> and on the docs site.</p>
<h2>Documentation</h2>
<p>Public documentation: <a href="https://sephera.vercel.app">https://sephera.vercel.app</a></p>
<p>Docs source lives in <a href="docs/"><code>docs/</code></a>, built as a static Astro Starlight site.</p>
<p>Useful local docs commands:</p>
<pre><code class="language-bash">npm run docs:dev
npm run docs:build
npm run docs:preview
</code></pre>
<h2>Workspace Layout</h2>
<ul>
<li><code>crates/sephera_cli</code>: CLI argument parsing, command dispatch, config resolution, and output rendering</li>
<li><code>crates/sephera_core</code>: shared analysis engine, traversal, ignore matching, <code>loc</code>, and <code>context</code></li>
<li><code>crates/sephera_mcp</code>: MCP server implementation (Model Context Protocol)</li>
<li><code>crates/sephera_tools</code>: explicit code generation and synthetic benchmark corpus generation</li>
<li><code>config/languages.yml</code>: editable source of truth for built-in language metadata</li>
<li><code>benchmarks/</code>: benchmark harness, generated corpora, reports, and methodology notes</li>
<li><code>docs/</code>: public documentation site</li>
<li><code>fuzz/</code>: fuzz targets, seed corpora, and workflow documentation</li>
</ul>
<h2>Development Checks</h2>
<pre><code class="language-bash">cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
npm run pyright
</code></pre>
<h2>License</h2>
<p>This repository is distributed under the GNU General Public License v3.0. See <a href="LICENSE"><code>LICENSE</code></a> for the full text.</p>

NAME

SYNOPSIS

INFO

DESCRIPTION

README