Skip to content

context

The context command prepares a focused context pack from a repository or sub-tree. It is designed for:

  • code review preparation
  • debugging support
  • onboarding into a codebase
  • LLM-assisted workflows that need bounded, explainable context

Use --path for local analysis or --url for direct remote analysis through a temporary checkout.

Terminal window
sephera context --path . --budget 8k # a bounded pack of this tree
sephera context --path . --focus crates/sephera_core --budget 8k --format markdown # one crate, as Markdown
sephera context --path . --list-profiles # profiles this repository defines

Run from inside the repository you want to pack.

A context pack currently contains:

  • structured metadata about the selected budget and files
  • dominant language summaries
  • grouped file sections such as focus, changes, entrypoints, testing, workflows, and general files
  • excerpts with truncation markers when the budget is tight
  • compressed AST excerpts when --compress is enabled

Focusing on a declaration rather than a file

Section titled “Focusing on a declaration rather than a file”

--focus <PATH> pulls in a whole file, which is right most of the time and wrong when one file carries far more than you need. --focus-symbol <NAME> packs the declaration instead:

Terminal window
sephera context --path . --focus-symbol resolve_import
sephera context --path . --focus-symbol resolve_import --focus-symbol clamp_to_root

Repeat the flag to pack several declarations. Matching is case-insensitive and partial, so resolve also finds resolve_source.

Two cases are reported rather than guessed, and both are deliberate:

  • a name matching several declarations, because picking one silently would put the wrong code in the pack and leave no sign of it
  • a name matching nothing, because the rest of the pack still builds and a reader would otherwise not notice the empty section

--focus-symbol cannot be combined with --diff. A diff selects whole changed files, and the two answer different questions: one names a declaration, the other names a change. Letting them combine would produce a pack whose contents depend on which of the two happened to match more.

Dependency closure: a pack that contains what it references

Section titled “Dependency closure: a pack that contains what it references”

Ranking alone packs a file and leaves what it imports to the general competition, where a dependency loses on size to unrelated files nothing in the pack needs. The result reads as a bag of files: the model holds the caller and not the callee. --closure builds the import graph and packs each file’s dependency chain directly behind it:

Terminal window
sephera context --path . --focus crates/sephera_graph/src/risk.rs --budget 8k --closure

Each file’s imports — and theirs, depth-first — are selected before any unrelated file that ranked below the file itself. Under a budget that runs out mid-chain, what is cut is the chain’s tail or the unrelated files, never a dependency passed over for a bystander its importer outranked. The pack’s metadata reports the count as Dependency closure pulls, so how much of the pack the graph is responsible for is stated rather than implied. On this repository, the command above packs 6 files, 5 of them pulled in by closure.

--closure cannot be combined with --focus-symbol: closure packs whole files behind their importers, and --focus-symbol packs parts of files and nothing else.

Generate Markdown to standard output:

Terminal window
sephera context --path .

Build a JSON context pack from a remote repository:

Terminal window
sephera context --url https://github.com/Reim-developer/Sephera --format json

Analyze a GitHub tree URL directly:

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

List the profiles available for the current repository config:

Terminal window
sephera context --path . --list-profiles
# Sephera Context Pack
## Metadata
| Field | Value |
| --- | --- |
| Base path | `.` |
| Focus paths | `crates/sephera_cli/src/run.rs` |
| Budget tokens | 128000 |
| Metadata budget tokens | 12800 |
| Excerpt budget tokens | 115200 |
| Estimated total tokens | 127860 |
| Estimated metadata tokens | 12776 |
| Estimated excerpt tokens | 115084 |
| Files considered | 13225 |
| Files selected | 519 |
| Truncated files | 0 |
## Dominant Languages
| Language | Files | Size (bytes) |
| --- | ---: | ---: |
| JavaScript | 5630 | 60338422 |
| TypeScript | 2744 | 16845759 |
| JSON | 516 | 7798487 |
| Markdown | 406 | 3496718 |
| Rust | 86 | 370095 |
...
sephera context --no-config --path crates/sephera_core --focus src/core/context --budget 8k grouped context output with bounded excerpts
Terminal demo of sephera context building a grouped Markdown context pack.

Focus on a sub-tree and export Markdown:

Terminal window
sephera context --path . --focus crates/sephera_core --budget 32k --format markdown --output reports/context.md

Export JSON instead:

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

Compress AST out of files using Tree-sitter, retaining only function signatures, structs, and imports:

Terminal window
sephera context --path . --compress signatures

Build a review pack from Git changes:

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

Center the pack on your current working tree:

Terminal window
sephera context --path . --diff working-tree

context --diff <SPEC> is a Git-only mode that prioritizes changed files before pulling in support files from the usual heuristics.

Built-in keywords:

  • working-tree: staged changes + unstaged changes + untracked files
  • staged: staged changes only
  • unstaged: unstaged changes + untracked files

Any other value is treated as a single base ref and compared against HEAD through merge-base semantics. Common examples:

  • origin/master
  • HEAD~1

Important behavior:

  • explicit --focus still wins over diff matches
  • changed files stay inside the selected --path
  • deleted files are counted in diff metadata but skipped from excerpts because there is no workspace content left to read
  • renamed files use the new path in the final report

In URL mode, only base-ref diffs are supported. These work:

  • main
  • master
  • HEAD~1
  • tags
  • commit SHAs

These are intentionally rejected in URL mode because the checkout is always clean:

  • working-tree
  • staged
  • unstaged

The --compress flag tells Sephera to use Tree-sitter to drop implementations and compress source files into API-only excerpts, significantly reducing the prompt burden. It replaces complex blocks with { ... }.

The saving scales with how much of a file is body. Measured on whole Rust files it runs 50-70%. On files that are mostly declarations there is little left to remove, and a file whose bodies are already one-liners can grow, because the { ... } markers and retained signatures cost more than the bodies they replace. Compressing an excerpt rather than a whole file saves very little, because an excerpt is already mostly declarations — measured at 0.4% across this repository.

Supported modes:

  • none (default): Standard full-text excerpts.
  • signatures: Retains structs, traits, imports, and function signatures. Eliminates implementation code.
  • skeleton: Similar to signatures, but keeps control-flow structures (such as if, for, match) without internal block details.

Languages with built-in AST support: Rust, Python, TypeScript, JavaScript, Go, Java, C++, C. If a file’s language is unsupported, Sephera automatically falls back to none (full excerpt) for that file.

The budget is an approximate token budget, not tokenizer-exact accounting. Sephera uses it to decide how much metadata and excerpt content can fit into a report without turning it into an unbounded repository dump.

Examples:

  • 32000
  • 32k
  • 1m

context now supports repo-level defaults and named profiles through .sephera.toml. The precedence order is:

  1. built-in defaults
  2. .sephera.toml
  3. selected profile, if any
  4. explicit CLI flags

Apply a named profile:

Terminal window
sephera context --path . --profile review

Use a profile and still override the diff target from the CLI:

Terminal window
sephera context --path . --profile review --diff staged

See the dedicated configuration page for details and examples.

  • --ref applies to repo URLs only and cannot be combined with tree URLs
  • auto-discovered .sephera.toml files inside a remote checkout still apply
  • --profile and --list-profiles work against remote config discovery
  • explicit --config <FILE> always refers to a local file on the machine running Sephera

Pack just what you need bounded excerpts, ranked with care exactly enough