Complete Reference

Complete Reference

Comprehensive documentation for LogicStamp Context CLI - all commands, options, features, examples, and troubleshooting guides.

5 Commands

15+ Options

3 Profiles

What's New in v0.1.0

📁

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

🛠️

New Commands

stamp init and stamp context clean for project setup and cleanup

⚛️

Next.js App Router Support

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

🛡️

CI/CD Improvements

--stats output optimized for CI parsing with token estimates

Commands

stamp init [path]Optional

Initialize LogicStamp in your project by setting up .gitignore patterns and generating LLM_CONTEXT.md

stamp context [path]

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

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	`1`
`--include-code <mode>`	`-c`	Code inclusion: none, header, or full	`header`
`--format <format>`	`-f`	Output format: json, pretty, or ndjson	`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`
`--predict-behavior`	`-`	Include experimental behavior predictions	`false`
`--dry-run`	`-`	Skip writing output; show summary only	`false`
`--stats`	`-`	Emit single-line JSON stats with token estimates	`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
• Behavioral predictions: disabled

llm-safe

Conservative mode for token-limited contexts

• Depth: 1
• Code: headers only
• Max nodes: 30
• Behavioral predictions: disabled

ci-strict

Strict validation mode for CI/CD

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

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.1",
  "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.1.0"
    }
  }
]

Examples

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

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

# 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

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

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

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 only analyzes .ts and .tsx files that export React components or functions.

Solution: Ensure your file has a named or default export that defines the component or function you care about.

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