context
context
Section titled “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.
sephera context --path . --budget 8k # a bounded pack of this treesephera context --path . --focus crates/sephera_core --budget 8k --format markdown # one crate, as Markdownsephera context --path . --list-profiles # profiles this repository definesRun from inside the repository you want to pack.
What the command includes
Section titled “What the command includes”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
--compressis 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:
sephera context --path . --focus-symbol resolve_importsephera context --path . --focus-symbol resolve_import --focus-symbol clamp_to_rootRepeat 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:
sephera context --path . --focus crates/sephera_graph/src/risk.rs --budget 8k --closureEach 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.
Basic usage
Section titled “Basic usage”Generate Markdown to standard output:
sephera context --path .Build a JSON context pack from a remote repository:
sephera context --url https://github.com/Reim-developer/Sephera --format jsonAnalyze a GitHub tree URL directly:
sephera context --url https://github.com/Reim-developer/Sephera/tree/master/crates/sephera_core --format jsonList the profiles available for the current repository config:
sephera context --path . --list-profilesSample Output
Section titled “Sample Output”# 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
Focus on a sub-tree and export Markdown:
sephera context --path . --focus crates/sephera_core --budget 32k --format markdown --output reports/context.mdExport JSON instead:
sephera context --path . --focus crates/sephera_core --format json --output reports/context.jsonCompress AST out of files using Tree-sitter, retaining only function signatures, structs, and imports:
sephera context --path . --compress signaturesBuild a review pack from Git changes:
sephera context --path . --diff HEAD~1 --budget 32kCenter the pack on your current working tree:
sephera context --path . --diff working-treeGit-aware diff mode
Section titled “Git-aware diff mode”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 filesstaged: staged changes onlyunstaged: 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/masterHEAD~1
Important behavior:
- explicit
--focusstill 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:
mainmasterHEAD~1- tags
- commit SHAs
These are intentionally rejected in URL mode because the checkout is always clean:
working-treestagedunstaged
AST Compression
Section titled “AST Compression”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 tosignatures, but keeps control-flow structures (such asif,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.
Budget model
Section titled “Budget model”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:
3200032k1m
Defaults and overrides
Section titled “Defaults and overrides”context now supports repo-level defaults and named profiles through .sephera.toml. The precedence order is:
- built-in defaults
.sephera.toml- selected profile, if any
- explicit CLI flags
Apply a named profile:
sephera context --path . --profile reviewUse a profile and still override the diff target from the CLI:
sephera context --path . --profile review --diff stagedSee the dedicated configuration page for details and examples.
URL mode notes
Section titled “URL mode notes”--refapplies to repo URLs only and cannot be combined with tree URLs- auto-discovered
.sephera.tomlfiles inside a remote checkout still apply --profileand--list-profileswork 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