Complete Reference

Comprehensive documentation for LogicStamp Context CLI - all commands, options, features, examples, and troubleshooting guides. Supports React, Vue 3, and TypeScript projects.

8 Commands

17+ Options

3 Profiles

MCP Server Integration (Beta v0.1.6)

LogicStamp Context now includes a Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop and Claude Code to analyze your codebase directly. The MCP server wraps the CLI and provides 4 core tools for snapshot-based analysis, component contracts, style metadata, and drift detection.

💡 Key Benefits: Install once, use everywhere. No manual file sharing—AI assistants can read component contracts, analyze style metadata, and verify changes automatically. Perfect for iterative development workflows.

MCP Server Documentation

What's New

v0.6.0 added runtime schema validation (AJV-enforced), fail-closed contract loading, path traversal protection, and security updates. Node.js >= 20 now required.

v0.5.5 improved strict watch mode with state-based diffing (like git diff), watch mode cleanup reliability on Windows/Cursor, and atomic writes.

v0.5.4 added graceful shutdown with centralized cleanup registry, improved debug logging, and reduced duplicated error handling.

v0.5.3 fixed JSON schema validation, race conditions, memory leaks, Windows path bugs, and improved performance (O(n²) → O(n) dependency collection).

v0.5.2 fixed JSON Schema completeness issues and documentation gaps.

v0.5.1 completed CSS-in-JS library support with Chakra UI and Ant Design, bringing coverage to all major CSS-in-JS libraries.

v0.5.0 introduced strict watch mode, schema improvements (BREAKING changes), and performance optimizations.

v0.4.x added watch mode with incremental rebuilds (v0.4.1) and backend framework support for Express.js and NestJS (v0.4.0).

v0.3.x releases included Next.js App Router features, dynamic Tailwind parsing, Vue.js support, and security improvements.

🔒

Runtime Schema Validation (v0.6.0)

AJV-enforced schema validation during contract loading. Invalid, malformed, or outdated contracts are rejected with capped, structured error reporting (max 20 errors). Fail-closed loading ensures contracts are rejected if schema fails to load.

🛡️

Security Hardening (v0.6.0)

Path traversal protection with strict project-root boundaries. File lock race condition fix prevents concurrent lock acquisition. Dependency security updates: glob@13.0.6 (patched minimatch ReDoS), ts-morph@27.0.2 with TypeScript 5.x support. Node.js >= 20 now required.

🔄

State-Based Strict Watch (v0.5.5)

Strict watch mode now compares current state vs the original baseline (like git diff), not cumulative history. Violations reflect current drift only and are automatically cleared when changes are reverted. Third-party packages removed from violations.

🧹

Watch Mode Reliability (v0.5.5)

Improved Windows/Cursor reliability with signal handlers at startup, absolute path resolution, synchronous cleanup on exit, and stale status file removal. Atomic writes prevent crash corruption. TOCTOU race condition fixed with file locking.

⚡

Performance & Bug Fixes (v0.5.3)

O(n²) to O(n) dependency collection, eliminated redundant file reads via caching. Fixed JSON schema validation, race conditions, memory leaks, and Windows path separator bugs. Type safety improvements across 10+ files.

🛡️

Strict Watch Mode (v0.5.0)

Track breaking changes and violations during watch mode with --strict-watch. Automatically detects breaking changes (removed props, events, state, functions; changed prop types; missing dependencies). Real-time violation reporting with cumulative tracking, structured JSON reports, and CI-friendly exit codes.

⚠️

BREAKING: Schema Field Renames (v0.5.0)

Renamed fields for clarity: MissingDependency.version → packageVersion, UIFContract.version → composition, UIFContract.logicSignature → interface. These BREAKING changes improve clarity and avoid confusion. Migration required for code parsing context bundles.

⚡

Performance Optimizations (v0.5.0)

O(1) dependency collection lookups replacing O(n) linear searches with Map-based index lookup. O(1) missing dependency tracking with Set-based lookup. Significantly improves performance for large projects during context generation.

🐛

Watch Mode Fixes (v0.5.0)

Fixed race condition in watch mode using Promise-based locking to ensure only one regeneration runs at a time. Fixed silent error swallowing in compare handler. Improved error handling and cleanup.

👀

Watch Mode (v0.4.1)

Monitor codebase for file changes and automatically regenerate context bundles. Incremental rebuilds only regenerate affected bundles. Change detection shows what changed (props, hooks, state, events). Debounces rapid changes (500ms). Watches style files when using --include-style. Debug mode shows hash information. Status file for tooling integration.

🔧

Framework Detection Fix (v0.4.1)

Fixed framework detection priority order: Backend > Vue > React > TypeScript module. Backend frameworks (Express/NestJS) are now correctly detected before Vue/React patterns, fixing issue where files with mixed patterns could be incorrectly classified.

🖥️

Backend Framework Support (v0.4.0)

Comprehensive support for Node.js backend frameworks (Express.js, NestJS). Extracts API routes, HTTP methods, route parameters, request/response types, and framework-specific metadata. Introduces node:api contract kind and extensible language:type pattern. Enhanced API signature extraction with multi-route aggregation and actual type extraction.

🔍

Hash Calculation Fix (v0.4.0)

Fixed hash calculation for backend files. Semantic and signature hashes now include backend metadata (routes, framework, controller, language-specific data) and apiSignature field. Backend route changes now properly trigger hash updates for accurate change detection.

⚛️

Advanced Next.js App Router (v0.3.10)

Enhanced Next.js metadata extraction with route roles, segment paths, and metadata exports. Automatically detects route roles (page, layout, loading, error, not-found, template, default, route). Extracts segment paths from file structure and parses both static (export const metadata) and dynamic (generateMetadata) metadata exports.

🎨

Dynamic Tailwind Parsing Phase 1 (v0.3.9)

Enhanced Tailwind CSS extractor to resolve dynamic class expressions within template literals. Resolves const/let variables, object properties, and conditional expressions (ternary, logical operators). Handles ~70-80% of common dynamic class patterns. Added support for additional variants (focus-visible, group/peer, ARIA, arbitrary selectors, container queries).

📦

Enhanced Third-Party Info (v0.3.8)

Missing dependencies now include package names and versions for third-party packages. Package name extraction handles scoped packages and subpath imports. Version lookup reads from package.json with caching for efficiency.

✅

Emit Detection Accuracy (v0.3.7)

Fixed issue where internal event handlers were incorrectly listed as component emits. Now only includes handlers that are part of the component's public API (props). Uses prop type signatures when available for accurate event signatures.

🔗

Hook Parameter Detection (v0.3.6)

Comprehensive support for extracting function signatures from custom React hooks, including parameter types, default values, and optional parameters. Works even when Props interfaces exist in the same file. Default depth changed from 1 to 2 for better nested component signature extraction.

💅

Styled JSX Support (v0.3.5)

Full CSS extraction from <style jsx> blocks with selector and property parsing using css-tree AST. Detects global attribute and handles complex selectors. Enhanced inline style extraction now extracts both property names and literal values from style={{ ... }} objects.

⚡

Vue.js Support (v0.3.4)

Comprehensive Vue 3 Composition API support: vue:component and vue:composable detection, reactive state extraction (ref, reactive, computed), props/emits from defineProps/defineEmits, lifecycle hooks, and composables. Works with .ts/.tsx files (JSX/TSX components). Note: .vue SFC files not yet supported.

📦

TOON Output Format (v0.3.3)

New --format toon option generates compact, AI-optimized TOON format bundles. Alternative to JSON/pretty/NDJSON formats. Creates context.toon files alongside context.json files.

🔧

Hook Classification (v0.3.1)

Custom React hooks are now correctly classified as react:hook instead of react:component. Detection logic checks if main export is a function starting with 'use' and has no JSX elements

🔒

Security Scanning (v0.3.0)

Security scan now runs by default during stamp init. Automatic secret sanitization in generated context files. New stamp ignore command for managing file exclusions

🚀

Enhanced Initialization (v0.3.0)

Security scan runs by default during stamp init. Use --no-secure to skip. --yes flag for non-interactive setup

🚫

File Exclusion (v0.3.0)

New stamp ignore command for managing .stampignore file. .stampignore is now independent of security scanning

📁

Relative Paths (v0.3.2)

Context files now use relative paths instead of absolute paths, improving portability across different machines and environments

🎨

AST-Based CSS Parsing (v0.3.2)

Migrated CSS/SCSS parsing from regex to AST-based parsing using css-tree for more robust and accurate extraction of selectors, properties, and SCSS features

🎨

Style Metadata Extraction

New stamp context style command extracts Tailwind, SCSS, Material UI, ShadCN/UI, Radix UI, animations, and layout patterns

🎭

Material UI Support

Detects Material UI components, packages, and styling features (theme, sx prop, styled components, makeStyles)

📊

Four-Mode Token Comparison

--compare-modes shows none, header, header+style, and full modes with accurate token counts

📁

Multi-File Output Structure

Generates multiple context.json files (one per folder) plus context_main.json index

🔍

Multi-File Context Drift Detection

Compare command supports multi-file mode with --approve and --clean-orphaned flags

⚛️

Next.js App Router Support

Detects 'use client' and 'use server' directives, identifies App Router files

🛡️

Optional Tokenizers

Automatic installation of @dqbd/tiktoken and @anthropic-ai/tokenizer for accurate token counts

Commands

stamp init [path]Optional

Initialize LogicStamp in your project by setting up .gitignore patterns and generating LLM_CONTEXT.md. Use --secure to automatically scan for secrets in JS/TS/JSON files

stamp security scan [path]

Scan JS/TS/JSON files for secrets (API keys, passwords, tokens) and optionally add detected files to .stampignore. Runs 100% locally

stamp context [path]

Scans a directory and generates multiple context.json files plus context_main.json index

stamp context style [path]

Generates context with style metadata (Tailwind, SCSS, animations, layout). Equivalent to --include-style

stamp context validate [file]

Checks context files for schema and structural issues before sharing or committing

stamp context compare [oldFile] [newFile]

Compares context files to detect drift across your project. Supports multi-file and single-file modes

stamp context clean [path]

Removes all generated context artifacts. Safe by default (dry run)

Options (context command)

Option	Alias	Description	Default
`--depth <n>`	`-d`	Dependency traversal depth. Default depth=2 includes nested components (e.g., App → Hero → Button). Depth=1 only includes direct dependencies.	`2`
`--include-code <mode>`	`-c`	Code inclusion: none, header, or full	`header`
`--format <format>`	`-f`	Output format: json, pretty, ndjson, or toon	`json`
`--out <file>`	`-o`	Output directory or file path	`context.json`
`--max-nodes <n>`	`-m`	Maximum nodes per bundle	`100`
`--profile <profile>`	`-`	Profile preset (see Profiles section)	`llm-chat`
`--strict`	`-s`	Fail on missing dependencies	`false`
`--dry-run`	`-`	Skip writing output; show summary only	`false`
`--stats`	`-`	Emit single-line JSON stats (ideal for CI). When combined with --compare-modes, writes context_compare_modes.json for MCP integration.	`false`
`--compare-modes`	`-`	Show detailed token comparison across all modes (none/header/header+style/full)	`false`
`--include-style`	`-`	Extract style metadata (Tailwind, SCSS, animations, layout)	`false`
`--skip-gitignore`	`-`	Skip .gitignore setup (never prompt or modify)	`false`
`--quiet`	`-q`	Suppress verbose output (show only errors)	`false`
`--help`	`-h`	Show help message	`-`

Profiles

Profiles are preset configurations optimized for different use cases:

llm-chat

Default

Balanced mode for AI chat interfaces

• Depth: 2
• Code: headers only
• Max nodes: 100

llm-safe

Conservative mode for token-limited contexts

• Depth: 2
• Code: headers only
• Max nodes: 30

ci-strict

Strict validation mode (contracts only, strict deps)

• Code: none
• Strict dependencies enabled
• Metadata-only mode

Style Metadata Extraction

The stamp context style command (or --include-style flag) extracts visual and layout information from your components, making context bundles design-aware for AI assistants. Supports Tailwind CSS, SCSS/CSS modules, Material UI, ShadCN/UI, Radix UI, inline styles, styled-components, and framer-motion.

What Gets Extracted

Style Sources

•Tailwind CSS classes (layout, spacing, colors, typography)
•SCSS/CSS modules (selectors, properties, features)
•Material UI components and styling (theme, sx prop, styled components, makeStyles)
•ShadCN/UI and Radix UI component patterns
•Inline styles and styled-components
•framer-motion animations and gestures

Layout Patterns

•Flex and grid layouts
•Hero sections and feature cards
•Responsive breakpoints (sm, md, lg, xl)
•Grid column configurations

Visual Metadata

•Color palettes (bg-*, text-*, border-*)
•Spacing patterns (padding, margin, gap)
•Border radius and typography classes
•Effects (shadows, opacity, filters)

Animation Metadata

•Animation library (framer-motion or CSS)
•Animation types (fade-in, slide, etc.)
•Trigger types (inView, hover, click)
•Viewport-triggered animations

Usage Examples

# 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 header

Token Comparison Modes

Use --compare-modes to see detailed token cost analysis across all available modes:

none10-20% of raw source

Contracts only (props, state, hooks, dependencies) with no source code

Best for: CI/CD validation, dependency analysis, maximum compression

header20-30% of raw source

Contracts plus JSDoc headers and function signatures

Best for: General AI chat workflows, code review, component interfaces

header+style40-60% of raw source

Header mode plus extracted style metadata (Tailwind, SCSS, animations)

Best for: UI/UX discussions, design system maintenance, visual consistency

full80-100% of raw source

Everything including complete source code

Best for: Deep implementation reviews, complex refactoring, debugging

Example Output

📊 Mode Comparison

   Comparison:
     Mode         | Tokens GPT-4o | Tokens Claude | Savings vs Raw Source
     -------------|---------------|---------------|------------------------
     Raw source   |        22,000 |        19,556 | 0%
     Header       |        12,228 |        10,867 | 44%
     Header+style  |        13,895 |        12,351 | 37%

   Mode breakdown:
     Mode         | Tokens GPT-4o | Tokens Claude | Savings vs Full Context
     -------------|---------------|---------------|--------------------------
     none         |         8,337 |         7,411 | 79%
     header       |        12,228 |        10,867 | 70%
     header+style |        13,895 |        12,351 | 30%
     full         |        39,141 |        34,792 | 0%

Optional Tokenizers for Accurate Counts

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 (normal for optional dependencies), the tool gracefully falls back to character-based estimation (typically within 10-15% accuracy).

Output Format

LogicStamp Context generates a folder-organized, multi-file output structure:

File Organization

output/
├── context_main.json          # Main index with folder metadata
├── context.json               # Root folder bundles (if any)
├── src/
│   └── context.json          # Bundles from src/ folder
├── src/components/
│   └── context.json          # Bundles from src/components/
└── src/utils/
    └── context.json          # Bundles from src/utils/

Main Index (context_main.json)

Provides a complete directory index with folder metadata and project summary:

{
  "type": "LogicStampIndex",
  "schemaVersion": "0.2",
  "projectRoot": ".",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "summary": {
    "totalComponents": 42,
    "totalBundles": 15,
    "totalFolders": 5,
    "totalTokenEstimate": 13895
  },
  "folders": [
    {
      "path": "src/components",
      "contextFile": "src/components/context.json",
      "bundles": 3,
      "components": ["Button.tsx", "Card.tsx"],
      "isRoot": false,
      "tokenEstimate": 5234
    }
  ]
}

Folder Context Files

Each folder's context.json contains an array of bundles (one bundle per root component/entry point):

[
  {
    "$schema": "https://logicstamp.dev/schemas/context/v0.1.json",
    "position": "1/5",
    "type": "LogicStampBundle",
    "schemaVersion": "0.1",
    "entryId": "src/components/Button.tsx",
    "depth": 1,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "bundleHash": "uifb:abc123...",
    "graph": {
      "nodes": [
        {
          "entryId": "src/components/Button.tsx",
          "contract": {
            "type": "UIFContract",
            "kind": "react:component",
            "description": "Button - Interactive component",
            "composition": {
              "variables": ["variant", "size"],
              "hooks": ["useState"],
              "components": [],
              "functions": ["handleClick"]
            },
            "interface": {
              "props": {
                "onClick": { "type": "function", "signature": "() => void" },
                "variant": { "type": "literal-union", "literals": ["primary", "secondary"] }
              }
            }
          }
        }
      ],
      "edges": []
    },
    "meta": {
      "missing": [],
      "source": "logicstamp-context@0.6.0"
    }
  }
]

Examples

Project Initialization

Set up LogicStamp in your project with optional security scanning

# Basic initialization (security scan runs by default)
stamp init

# Initialize without prompts (CI-friendly, security scan still runs)
stamp init --yes

# Initialize without security scan
stamp init --no-secure

# Initialize a specific directory
stamp init ./my-project

# Initialize without security scan for a specific directory
stamp init ./my-project --no-secure

Security Scanning

Scan for secrets and sensitive data before committing

# Scan current directory for secrets
stamp security scan

# Scan specific directory
stamp security scan ./src

# Review report and exclude files with secrets
stamp ignore src/secrets.ts

# Save report to custom file
stamp security scan --out security-report.json

# Quiet mode (suppress verbose output)
stamp security scan --quiet

Basic Usage

Generate context for entire project

# Generate context for entire project
stamp context

# CLI output shows scanning, analysis, and validation steps

Focused Analysis

Analyze only specific directories

# Analyze only the src directory
stamp context ./src

# Analyze with custom output file
stamp context --out my-context.json

Deep Traversal

Include more dependency levels. Recommended: depth=2 for React projects to include nested components in dependency graphs.

# Recommended: depth=2 for React projects (includes nested components)
stamp context --depth 2

# Include 3 levels of dependencies
stamp context --depth 3

# Include full source code
stamp context --include-code full

Token Cost Analysis

Get token estimates for different modes

# Get JSON stats for CI
stamp context --stats

# Compare all modes (none/header/header+style/full)
stamp context --compare-modes

# See token costs for specific mode
stamp context --include-code none
stamp context --include-code header
stamp context --include-code full

# Include style metadata
stamp context --include-style

Style Metadata Extraction

Generate design-aware context with visual and layout information

# Generate context with style metadata
stamp context style

# Equivalent using flag
stamp context --include-style

# Style with specific options
stamp context style --profile llm-safe
stamp context style --include-code header

CI/CD Validation

Use in continuous integration pipelines

# Use llm-safe profile for smaller output
stamp context --profile llm-safe

# Strict mode: fail if any dependencies missing
stamp context --strict

# Generate stats for CI monitoring
stamp context --stats > stats.json

# Validate generated context
stamp context validate context_main.json

# Check for drift across all folders
stamp context compare --stats

# Compare token costs across modes
stamp context --compare-modes

Troubleshooting

🔍

Handling Missing Dependencies

External Packages

This is normal. LogicStamp only analyzes your source code, not node_modules.

Solution: External packages are intentionally excluded.

File Not Found

Referenced file doesn't exist (deleted or moved).

Solution: Check if the file was deleted or moved, update the import path, or use --strict in CI.

Outside Scan Path

File exists but outside the specified scan directory.

Solution: Expand your scan path: stamp context ../ or scan from project root.

Max Depth Exceeded

Dependency beyond --depth limit.

Solution: Increase depth: stamp context --depth 2 or --depth 3. Note: Higher depth = more tokens.

❓

Common Questions

How do I scan only a specific folder?

By default, LogicStamp respects .gitignore and skips node_modules/, .next/, dist/, and other build directories.

Solution: Scan a directory directly: stamp context ./src

How do I exclude additional folders?

LogicStamp uses .gitignore as the source of truth for what to skip.

Solution: Add folders to .gitignore or pass a direct path (e.g. stamp context ./src) to restrict the scan.

Why don't I see context for some components?

LogicStamp analyzes .ts and .tsx files that export React components, Vue components/composables, or functions. For Vue projects, works with JSX/TSX components and extracted composables. Note: .vue SFC files are not currently supported.

Solution: Ensure your file has a named or default export that defines the component or function you care about. For Vue projects, extract logic to .ts/.tsx files or use JSX/TSX syntax.

How do I get the best results in AI chat?

AI assistants work best when you give them a single, structured view of your project.

Solution: When prompting an AI assistant, explicitly tell it to use the per-folder context.json files and the root context_main.json to understand your project structure.

Next Steps

Explore the complete CLI documentation or review additional guides.

Installation & Quick Start What is LogicStamp?GitHub Repository