Stenography generates deterministic context packs for coding agents under a token budget.
It is not a generic short-writing project. It is a repo-local packing layer that turns task input, repo summaries, and optional analysis JSON into a compact Markdown pack plus JSON metadata that other workflow tools can consume.
- Contribution workflow: CONTRIBUTING.md
- Architecture boundaries: docs/architecture.md
- Context-packing design: docs/design/context-packing.md
- Token-savings methodology: docs/evals/token-savings-methodology.md
- Golden examples: docs/evals/golden-examples.md
- Durable decisions: docs/adr/
- A/R/N Pattern: Replaces verbose natural language with structured blocks:
A:Answer (direct, no fluff)R:Reason (logical derivation/facts)N:Next step (actionable directions)
- Symbolic Logic Mapping: Replaces prose conjunctions/logic paths with logic operators (
→for causality,∃for checks,!=for inequality). - Namespace Scoping: Translates narrative statements to key-value maps (
sys.env: devinstead of "The system environment is configured for development"). - Standard Abbreviations: Uses world-standard short names (
fn,db,config,pkg,repo,dev) that LLMs parse natively without loss of meaning. - Lazy Resolution: Resolves references via file links rather than copy-pasting raw content.
The table below is a target hypothesis for eval design, not a measured claim. Treat performance numbers as measured only when an AgentLens artifact is linked from a report that follows docs/evals/token-savings-methodology.md.
| Metric / Style | Verbose (Default) | Caveman | Stenography (Symbolic) |
|---|---|---|---|
| Output Token Size | 100% (baseline) | target: ~25% | target: ~30% |
| Input Context Size | 100% (baseline) | target: ~35% | target: ~35% |
| Human Readability | High | Extremely low (broken prose) | High (logical structure) |
| Technical Accuracy | High | Moderate (risks ambiguity) | High (retains logical relationships) |
| Speed (TTFT/Generation) | 1x | target: ~3x | target: ~3x |
Automatically parses a target markdown file, strips grammatical fluff, maps logic to symbols, and rewrites the file in place to save active context space.
Stenography also ships a standalone CLI for deterministic context packs:
stenography pack \
--repo . \
--task issue-123.md \
--budget 30000 \
--analysis analysis/issue-123.json \
--output .stenography/packs/issue-123.pack.md
stenography summarize-repo --repo . --output .stenography/repo-summary.md
stenography validate-pack .stenography/packs/issue-123.pack.jsonContract: docs/context-pack-contract.md
Boundaries:
- Stenography owns deterministic context-pack generation.
- External workflow tools may call the CLI.
- External analysis tools may produce optional JSON consumed through
--analysis. - AgentLens may measure token savings and task outcomes.
Stenography must not depend on any specific orchestrator or repo-understanding engine.
See INSTALL.md for details on setting up Stenography configuration files in Claude Code, GitHub Copilot, Cursor, and Codex / Antigravity.