Complete Reference | LogicStamp Context Documentation

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.2)

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 in v0.3.x

The 0.3.x releases include major framework support, output format options, and security improvements. v0.3.4 adds comprehensive Vue.js support for Vue 3 Composition API. v0.3.3 introduced TOON output format support. v0.3.2 improved portability with relative paths and AST-based CSS/SCSS parsing. v0.3.1 fixed hook classification. v0.3.0 introduced security scanning by default and automatic secret sanitization.

⚡

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. Recommended: depth=2 for React projects to include nested components (e.g., App → Hero → Button). Default depth=1 only includes direct dependencies.	`1`
`--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: 1
• Code: headers only
• Max nodes: 100

llm-safe

Conservative mode for token-limited contexts

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

ci-strict

Strict validation mode for CI/CD

• 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",
            "version": {
              "variables": ["variant", "size"],
              "hooks": ["useState"],
              "components": [],
              "functions": ["handleClick"]
            },
            "logicSignature": {
              "props": {
                "onClick": { "type": "function", "signature": "() => void" },
                "variant": { "type": "literal-union", "literals": ["primary", "secondary"] }
              }
            }
          }
        }
      ],
      "edges": []
    },
    "meta": {
      "missing": [],
      "source": "logicstamp-context@0.3.4"
    }
  }
]

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.

Ready to Get Started?

Now that you understand the complete reference, check out the installation guide or explore more documentation.

Installation & Quick Start What is LogicStamp?GitHub Repository