stamp context Command
Generate AI-ready bundles that describe your React/TypeScript codebase.
Syntax
stamp context [path] [options][path] (optional) – Directory to scan. Defaults to the current working directory. Paths can be relative (for example, ./src) or absolute.
Output Structure
LogicStamp Context generates folder-organized, multi-file output:
Multiple context.json files, one per folder containing components
Directory structure mirrors your project layout
context_main.json index file at the output root with folder metadata
Each folder containing components gets its own context.json file with bundles for that folder's components. The context_main.json file serves as a directory index with summary statistics and folder metadata.
First Run Behavior
stamp context is CI-friendly and never prompts. It respects preferences saved in .logicstamp/config.json from stamp init. On first run (no config), it defaults to skipping both .gitignore and LLM_CONTEXT.md setup for CI-friendly behavior. Use stamp init to configure these options (non-interactive by default; use --no-secure for interactive mode).
Use stamp init to set up .gitignore patterns and LLM_CONTEXT.md before generating context files. Non-interactive by default (use --no-secure for interactive mode).
Use --skip-gitignore flag to skip .gitignore setup on a per-run basis (useful for CI environments).
File Exclusion: stamp context respects .stampignore and excludes those files from context generation. You'll see how many files were excluded (unless using --quiet). Use stamp ignore <file> to add files to .stampignore. .stampignore is completely optional and independent of security scanning.
Secret Sanitization: If a security report (stamp_security_report.json) exists, stamp context automatically replaces detected secrets with "PRIVATE_DATA" in the generated JSON files. Your source code files are never modified - only the generated context files contain sanitized values.
CI-friendly: stamp context never prompts and respects preferences from stamp init. Your preferences are saved in .logicstamp/config.json.
Behavior
Each run of stamp context performs a full scan, generates context files organized by folder, and then automatically validates the generated context before writing it to disk. The CLI output shows both the generation and validation steps so you can see when schema issues are caught.
Options
| Option | Default | Description |
|---|---|---|
--depth <n> | 1 | Dependency traversal depth (0 = entry only, 1 = direct deps, etc.). |
--include-code <mode> | header | Include none, header, or full source snippets. |
--format <fmt> | json | Output format: json, pretty, ndjson, or toon. |
--out <file> | context.json | Output directory or file path. If a .json file is specified, its directory is used as the output directory. Otherwise, the path is used as the output directory. Context files will be written maintaining folder structure within this directory. |
--max-nodes <n> | 100 | Maximum graph nodes per bundle. |
--profile <name> | llm-chat | Preset configuration (llm-chat, llm-safe, ci-strict). |
--strict | false | Fail when dependencies are missing. |
--strict-missing | false | Exit with error if any missing dependencies found. |
--predict-behavior | false | Experimental behavioral prediction annotations. |
--dry-run | false | Skip writing the output; display summary only. |
--stats | false | Emit single-line JSON stats (ideal for CI). When combined with --compare-modes, writes context_compare_modes.json for MCP integration. |
--compare-modes | false | Show detailed token comparison table across all modes (none/header/header+style/full) with accurate style metadata impact. When combined with --stats, writes context_compare_modes.json for MCP (Model Context Protocol) integration. |
--include-style | false | Extract style metadata (Tailwind, SCSS, Material UI, animations, layout). |
--skip-gitignore | false | Skip .gitignore setup (never prompt or modify). |
--quiet | false | Suppress verbose output (show only errors). |
--help | -h | Print usage help. |
Example Workflows
# Scan entire repo and write context files (defaults)
stamp context
# Creates: context_main.json + context.json files in each folder
# Generate context for ./src with pretty-printed output
stamp context ./src --format pretty
# Include full source for deep AI reviews (limit nodes for safety)
stamp context --include-code full --max-nodes 20
# Gather metrics without writing files (e.g., CI dashboards)
stamp context --stats >> .ci/context-stats.jsonl
# Dry run to confirm counts before generating files
stamp context ./packages/ui --dry-run
# Suppress verbose output (quiet mode)
stamp context --quiet
# Generate context with style metadata
stamp context style
# Or use the flag (equivalent)
stamp context --include-style
# Compare token costs across all modes (including style)
stamp context --compare-modes
# See compare-modes.md for comprehensive guide
# Generate comparison data file for MCP integration
stamp context --compare-modes --stats
# Creates: context_compare_modes.json with structured comparison data
# Custom output directory
stamp context --out ./output
# Or specify a file to use its directory
stamp context --out ./output/context.json
# Generate TOON format (compact, AI-optimized)
stamp context --format toon
# Creates: context_main.json + context.toon files in each folderTOON Format Support
LogicStamp supports TOON format as an alternative output format for context bundles. TOON provides a compact binary-like encoding optimized for AI consumption and efficient storage. When you use --format toon, LogicStamp generates context.toon files instead of context.json files.
TOON format encodes the same LogicStamp bundle structure as JSON, but in a more compact representation. The main index file (context_main.json) is always in JSON format, even when using TOON format for bundles.
# Generate TOON format bundles
stamp context --format toon
# Output structure:
# output/
# ├── context_main.json # Always JSON
# ├── context.toon # TOON format bundles
# └── src/
# └── context.toon # TOON format bundlesLearn more: Read the complete TOON format documentation →
Secret Sanitization
When generating context files, LogicStamp automatically sanitizes secrets if a security report exists.
How it works
- If
stamp_security_report.jsonexists in your project root, it's automatically used - Secrets detected in the security report are replaced with
"PRIVATE_DATA"in generated JSON files - Your source code files are never modified - only the generated context files are affected
Example
Source code:
const apiKey = 'FAKE_EXAMPLE_KEY_DO_NOT_USE';
const password = 'FAKE_EXAMPLE_PASSWORD_DO_NOT_USE';Generated context.json:
{
"code": "const apiKey = 'EXAMPLE_PRIVATE_DATA';
const password = 'EXAMPLE_PRIVATE_DATA';"
}Important
- ✅ Source files remain unchanged
- ✅ Sanitization happens automatically (no flags needed)
- ✅ Works with all code inclusion modes (
--include-code none,header,full) - ✅ Applies to both
stamp contextandstamp context style
Code inclusion modes and credentials: Even if credentials exist in your source files (which they shouldn't), they can only be included in generated bundles when using --include-code full mode. The other modes (none, header, header+style) only include metadata and contracts, not actual implementation code where credentials would typically be found.
Understanding meta.missing
An empty missing array means all dependencies were resolved. Non-empty means some couldn't be found.
Expected (safe to ignore)
External packages (React, lodash, etc.)
Actionable
"file not found" (broken imports), "outside scan path" (expand scan directory), "max depth exceeded" (increase --depth)
Use --strict-missing in CI to catch unexpected missing dependencies:
stamp context --strict-missing || exit 1