Usage Guide
Learn how to use LogicStamp Context effectively in local development and CI workflows.
Quick Start
# Install globally
npm install -g logicstamp-context
# Initialize (non-interactive by default, security scan runs automatically)
stamp init
# Generate context for your project
stamp context
# Output: Multiple context.json files (one per folder)
# plus context_main.json indexNote: "Global CLI" means the tool is installed globally on your system (via npm install -g), making the stamp command available from any directory in your terminal, not just within a specific project folder.
- Local install:
npm install logicstamp-context→ only available in that project - Global install:
npm install -g logicstamp-context→ available everywhere viastampcommand
🔒 Security Best Practice: By default, stamp init is non-interactive because it automatically runs a security scan to detect secrets in your JS/TS/JSON files. This prevents sensitive data from being included in context files. Use --no-secure to skip the security scan and enable interactive prompts (in TTY mode).
Command Syntax
stamp --version # Show version number
stamp --help # Show help
stamp init [path] [options] # Initialize LogicStamp in project
stamp ignore <path> [path2] ... # Add files/folders to .stampignore
stamp context [path] [options]
stamp context style [path] [options] # Generate context with style metadata
stamp context validate [file]
stamp context compare [oldFile] [newFile] [options] # Auto-mode (default): omit files to compare all context files
stamp context clean [path] [options]
stamp security scan [path] [options] # Scan for secrets and generate report
stamp security --hard-reset [options] # Reset security configurationUse stamp init to set up your project (non-interactive by default, security scan runs automatically; optional, stamp context is CI-friendly and never prompts), stamp security scan to find secrets in your JS/TS/JSON files before generating context, stamp context to generate folder-organized context files, stamp context style to generate context with style metadata (Tailwind, SCSS, animations), stamp context validate to verify them, stamp context compare to detect drift across all folders, and stamp context clean to remove context artifacts.
Global Options
These options are available at the top level (before any subcommand):
| Option | Alias | Description |
|---|---|---|
--version | -v | Show version number and exit |
--help | -h | Show help message and exit |
Examples:
stamp --version # Shows: fox mascot + "Version: 0.3.5"
stamp -v # Same as --version
stamp --help # Shows main help
stamp -h # Same as --helpstamp ignore Command
Add files or folders to .stampignore to exclude them from context generation. This is useful for excluding files with secrets, large generated files, or other files that shouldn't be included in context bundles.
Arguments
<path1> [path2] ... – One or more file or folder paths to ignore (relative to project root). Supports glob patterns.
Key Options
| Option | Alias | Description |
|---|---|---|
--quiet | -q | Suppress verbose output (show only errors) |
Examples
# Add a single file to .stampignore
stamp ignore src/secrets.ts
# Add multiple files/folders
stamp ignore src/config/credentials.ts src/secrets/
# Add glob patterns
stamp ignore "**/secrets.ts" "**/*.key"
# Quiet mode
stamp ignore src/secrets.ts --quietWhat It Does
- Creates
.stampignoreif it doesn't exist - Adds specified paths to
.stampignore - Prevents duplicate entries
- Normalizes paths automatically
- Shows feedback about what was added (unless
--quietis used)
Integration with Other Commands
- Files in
.stampignoreare automatically excluded when runningstamp context - Use
stamp ignore <file>to add files with detected secrets to.stampignoreafter reviewing the security report
Common Options
--depthControl how far dependency traversal should go (0 = entry only, 1 = direct dependencies).
--include-codeChoose between none, header, or full code snippets.
--include-styleExtract style metadata (Tailwind, SCSS, animations, layout patterns).
--compare-modesShow detailed token comparison across all modes (none/header/header+style/full).
--profileApply preset settings like llm-chat, llm-safe, or ci-strict.
--dry-run & --statsIdeal for CI dashboards and automation.
CI and Automation Tips
By default, stamp init is non-interactive because it automatically runs a security scan to detect secrets in your JS/TS/JSON files before generating context. Use --no-secure to enable interactive mode.
After running stamp security scan, review the report and use stamp ignore <file> to exclude files with detected secrets from context generation.
Use --dry-run to inspect bundle size and counts without producing files.
Use --stats to emit machine-readable summary lines and append them to logs or dashboards.
Use --compare-modes to see token costs across all modes (none/header/header+style/full) before generating context.
Use stamp context style or --include-style to generate design-aware context with visual and layout metadata.
Use stamp context compare in CI to detect context drift across all folders. Use --approve for auto-updates (like Jest snapshots).
Combine stamp security scan, stamp context, and stamp context validate in pre-commit hooks or CI jobs to keep context files secure and in sync.
Use stamp context clean --all --yes to reset context files before regenerating or switching branches.
Style Metadata Extraction
Generate design-aware context bundles with visual and layout information using stamp context style or the --include-style flag.
# Generate context with style metadata
stamp context style
# Equivalent using flag
stamp context --include-style
# With specific options
stamp context style --profile llm-safe
stamp context style --include-code headerWhat Gets Extracted
- • Tailwind CSS classes (layout, spacing, colors)
- • SCSS/CSS module imports and details
- • Layout patterns (flex, grid, hero sections)
- • Animation metadata (framer-motion, CSS)
- • Visual patterns (colors, spacing, typography)
Use Cases
- • Design system analysis
- • AI-assisted design suggestions
- • Layout understanding
- • Animation detection
- • Style consistency tracking
Token Cost Comparison
Use --compare-modes to see detailed token cost analysis across all available modes before generating context.
# Compare token costs across all modes
stamp context --compare-modes
# Output shows:
# - none: Contracts only (10-20% of raw source)
# - header: Contracts + JSDoc headers (20-30% of raw source)
# - header+style: Header + style metadata (40-60% of raw source)
# - full: Complete source code (80-100% of raw source)Optional Tokenizers: LogicStamp Context includes @dqbd/tiktoken (GPT-4) and @anthropic-ai/tokenizer (Claude) as optional dependencies. npm automatically attempts to install them when you install logicstamp-context. If installation succeeds, you get model-accurate token counts. If installation fails or is skipped, the tool gracefully falls back to character-based estimation (typically within 10-15% accuracy).
Example Workflows
Basic Context Generation
# Generate context for entire project
stamp context
# Scan specific directory
stamp context ./src
# Custom output directory
stamp context --out ./outputStyle-Aware Context
# Generate context with style metadata
stamp context style
# Or use the flag
stamp context --include-style
# With conservative profile
stamp context style --profile llm-safeToken Cost Analysis
# Compare all modes before generating
stamp context --compare-modes
# Generate with specific mode
stamp context --include-code header
stamp context --include-code full --max-nodes 20CI/CD Integration
# Scan for secrets first (fail build if found)
stamp security scan --quiet
# Generate stats for monitoring
stamp context --stats > stats.json
# Validate generated context
stamp context validate
# Check for drift
stamp context compare --stats
# Auto-approve updates
stamp context compare --approveSecurity Workflow
# Initialize (non-interactive by default, security scan runs automatically)
stamp init
# Or scan manually before generating context
stamp security scan
# Review the report and exclude files with secrets
stamp ignore src/secrets.ts
# Generate context (secrets are sanitized automatically)
stamp context
# Regular security checks
stamp security scan