logicstamp-context

The Context Compiler for TypeScript.

Supports: React · Next.js · Vue (TS/TSX) · Express · NestJS

LogicStamp Context is a CLI that compiles TypeScript codebases into deterministic, diffable architectural contracts and dependency graphs - a compact, structured source of truth for AI coding workflows.

Includes watch mode, strict, auditable diffs, and real-time breaking change detection.
Use with logicstamp-mcp to feed structured context into Claude, Cursor, and other MCP-compatible assistants.

• The Problem
• Quick Start
• Why Structured Context?
• Features
• Watch Mode
• How it Works
• MCP Server
• Security
• Usage
• Framework Support
• Documentation
• Known Limitations
• Benchmarks
• Requirements
• Need Help?
• License

The Problem

AI coding assistants read your source code - but they don’t understand its structure.
They hallucinate props, miss dependencies, and can’t detect when a breaking change impacts consumers.

Example: your Button accepts variant and disabled, but the AI suggests isLoading because it saw that pattern elsewhere. Without a structured contract, there is no reliable source of truth.

LogicStamp Context derives that layer from your TypeScript - explicit interfaces and dependency structure for tools to consume instead of inferring from implementation.

Example workflow: stamp context --strict-watch generates context bundles that MCP-powered assistants use to explain component architecture (ThemeContext shown here).

TypeScript Code  →  Compilation  →  Deterministic Contracts  →  AI Assistant
   (.ts/.tsx)        (ts-morph)       (context.json bundles)     (Claude, Cursor)

Quick Start

No install required:

npx logicstamp-context context

Scans your repo and writes context.json files + context_main.json for AI tools.

What you get:

• 📁 context.json files - one per folder with components, preserving your directory structure
• 📋 context_main.json - index file with project overview and folder metadata

Installation

For ongoing use, install the CLI globally:

npm install -g logicstamp-context

The stamp command is then available everywhere. Initialize and generate context:

stamp init        # sets up .gitignore, scans for secrets
stamp context

ℹ️ Note: With npx, run npx logicstamp-context context. after a global install, use stamp context. If npx breaks but stamp works, remove the stale global CLI (npm uninstall -g logicstamp-context) and reinstall or run npx logicstamp-context@latest context.

📋 For detailed setup instructions, see the Getting Started Guide.

Why Structured Context?

Key insight: AI assistants don’t need your implementation - they need your interfaces.
LogicStamp extracts what matters and discards the noise.

What "Structured" Means

Instead of sending raw source code to AI:

// Raw: AI must parse and infer
export const Button = ({ variant = 'primary', disabled, onClick, children }) => {
  const [isHovered, setIsHovered] = useState(false);
  // ... 150 more lines of implementation
}

LogicStamp Context generates:

{
  "kind": "react:component",
  "interface": {
    "props": {
      "variant": { "type": "literal-union", "literals": ["primary", "secondary"] },
      "disabled": { "type": "boolean" },
      "onClick": { "type": "function", "signature": "() => void" }
    }
  },
  "composition": { "hooks": ["useState"], "components": ["./Icon"] }
}

Pre-parsed. Categorized. Stable. The AI reads contracts, not implementations.

On disk, each folder’s context.json is a LogicStampBundle: contracts live under graph.nodes, with graph.edges for dependencies. context_main.json indexes folders and metadata. Full JSON shape: docs/reference/schema.md.

⚡ Features

Under the hood: the TypeScript compiler API (via ts-morph). Analysis-only - it describes your codebase and emits context files. it does not transform or refactor your source.

Core:

• Deterministic contracts - Same input = same output, auditable in version control
• Watch mode - Auto-regenerate on file changes with incremental rebuilds
• Breaking change detection - Strict watch mode catches removed props, events, functions in real-time
• MCP-ready - AI agents consume context via standardized MCP interface

Analysis:

• React/Next.js/Vue component extraction (props, hooks, state, deps)
• Backend API extraction (Express.js, NestJS routes and controllers)
• Dependency graphs (handles circular dependencies)
• Style metadata extraction (Tailwind, SCSS, MUI, shadcn)
• Next.js App Router detection (client/server, layouts, pages)

Developer experience:

• Per-folder bundles matching your project structure
• Accurate token estimates (GPT/Claude)
• Security-first: automatic secret detection and sanitization
• Zero config required - sensible defaults, works out of the box

How it fits your stack

• Works alongside tsc - Focuses on contract structure and change detection, not type-checking. Use tsc --noEmit for compiler errors. compare --strict and --strict-watch flag contract-level breaking changes.
• Beyond .d.ts - Adds semantic contracts, dependency graphs, and diffable hashes (semanticHash, bundleHash) alongside declaration surfaces.
• Context, not control - Feeds structured context to assistants. Decisions stay with you.

📋 For detailed behavior, CLI options, and workflows, see the Usage guide.

Watch Mode

Strict watch mode in action: detecting violations and clearing them when resolved.

For development, run watch mode to keep context fresh as you code:

stamp context --watch                  # regenerate on changes
stamp context --strict-watch           # also detect breaking changes (implies --watch)

Strict watch catches breaking changes that affect consumers:

Errors vs Warnings: Violations are classified by severity:

❌ Errors indicate breaking changes that will affect consumers (removed props, events, functions, or entire contracts).

⚠️ Warnings indicate less severe changes (type signature changes, removed internal state). Violations are tracked in real-time and automatically cleared when resolved.

Session Status Tracking: Strict watch mode displays a session status block showing cumulative statistics:

• Errors/Warnings detected: Total violations detected during the session
• Resolved: Number of times all violations were completely resolved
• Active: Current number of active violations

The status block only appears when violations change (not on every file change), keeping terminal output clean.

Example terminal output showing violations and session status.

ℹ️ Note: Strict Watch currently detects breaking changes at the source. Next step: a symbol-level import/export reverse index to trace which consumer files will break. See docs/cli/watch.md for complete documentation.

One-time Comparison

Compare regenerated context against existing files:

stamp context compare            # detect changes
stamp context compare --approve  # update (like jest -u)

Useful for reviewing changes before committing or validating context is up-to-date.

Git baseline comparison (v0.7.2): Compare against any git ref:

stamp context compare --baseline git:main      # Compare against main branch
stamp context compare --baseline git:HEAD      # Compare against HEAD
stamp context compare --baseline git:v1.0.0    # Compare against a tag

ℹ️ Note: Context files are gitignored by default. Git baseline comparison uses git worktrees to generate context for both the baseline ref and the current working tree, then performs a structural contract comparison. See docs/cli/compare.md for complete documentation.

How it Works

The compilation pipeline:

1. Scan - Discovers all .ts and .tsx source files
2. Parse - Builds AST (Abstract Syntax Tree) via ts-morph using the TypeScript compiler API
3. Extract - Compiles contracts with props, hooks, state, signatures
4. Graph - Resolves dependency relationships
5. Emit - Outputs context.json bundles per folder
6. Index - Generates context_main.json with metadata and statistics

One command. No build step required.

💡Tip: Use stamp context for basic contracts. Use stamp context style when you need style metadata (Tailwind classes, SCSS selectors, layout patterns). Use --style-mode lean (default) for compact output or --style-mode full for detailed arrays.

MCP Server

For AI assistants with MCP support (Claude Desktop, Cursor, etc.):

npm install -g logicstamp-mcp

Then configure your AI assistant to use the LogicStamp MCP Server.

🔗 See LogicStamp MCP Server Repository

📋 See MCP Getting Started Guide for setup instructions.

Security

Automatic Secret Protection

LogicStamp Context protects sensitive data in generated context:

• Security scanning by default - stamp init scans source files (.ts, .tsx, .js, .jsx) and .json files for hard-coded secrets before context compilation
• Automatic sanitization - Detected secrets replaced with "PRIVATE_DATA" in output
• Manual exclusions - Use stamp ignore <file> to exclude files via .stampignore
• Safe by default - Only metadata included. Credentials only appear in --include-code full mode

⚠️ Seeing "PRIVATE_DATA" in output? Review stamp_security_report.json, remove hardcoded secrets from source, use environment variables instead.

🔒 See SECURITY.md for complete security documentation.

Usage

stamp --version                    # Show version
stamp --help                       # Show help
stamp init [path]                  # Initialize project (security scan by default)
stamp ignore <path>                # Add to .stampignore
stamp context [path]               # Generate context bundles
stamp context style [path]         # Generate with style metadata (lean mode by default)
stamp context style --style-mode full  # Generate with full style details (verbose)
stamp context --watch              # Watch mode
stamp context --strict-watch       # Watch with breaking change detection (--watch optional)
stamp context compare              # Detect changes vs existing context
stamp context validate [file]      # Validate context files
stamp context clean [path]         # Remove generated files

Common Options

📋 See docs/cli/commands.md for complete reference.

Framework Support

ℹ️ Note: LogicStamp Context analyzes .ts and .tsx files only. JavaScript files are not analyzed.

Documentation

Full documentation at logicstamp.dev/docs

• Getting Started Guide
• Usage Guide
• Monorepo Support
• Output Schema
• UIF Contracts
• Watch Mode
• Troubleshooting

Known Limitations

LogicStamp Context is in beta. Some edge cases are not fully supported.

📋 See docs/reference/limitations.md for the full list.

Benchmarks

You can compare bundle token costs across modes on your repo with stamp context --compare-modes (see compare modes).

Formal benchmarks are on the roadmap:

• CLI/runtime baselines
• LLM evaluations (with vs without LogicStamp context)

Requirements

• Node.js >= 20
• TypeScript codebase - .ts / .tsx only (JavaScript is not yet analyzed). Frameworks, UI libraries, and limits: Framework support.

Need Help?

• Issues - github.com/LogicStamp/logicstamp-context/issues
• Roadmap - logicstamp.dev/roadmap

License

MIT

The LogicStamp Fox mascot and related brand assets are © 2025 Amit Levi. These assets may not be used for third-party branding without permission.

Issues and PRs welcome! See CONTRIBUTING.md for guidelines.

This project follows a Code of Conduct.

Links: Website · GitHub · MCP Server · Changelog