GitHub - LogicStamp/logicstamp-context: Structured context for AI coding assistants. Deterministic component contracts from TypeScript.

Structured context for AI coding assistants.

Make AI coding assistants understand your architecture, not just your code.
Extract deterministic component contracts from your TypeScript codebase.

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

Works with Claude, Cursor, Copilot Chat, and any MCP-compatible agent.

LogicStamp Context is a static analyzer that extracts deterministic component contracts from TypeScript codebases - giving AI assistants structured architectural context instead of raw source code.

📑 Table of Contents

The Problem
Quick Start
Why Structured Context?
Features
Watch Mode
One-time Comparison
How it Works
MCP Server
Example Output
Installation
Security
Usage
Framework Support
Documentation
Known Limitations
Requirements
Need Help?
License

The Problem

AI coding assistants read your source code, but they don't understand it structurally. They hallucinate props that don't exist, miss dependencies, and can't tell when a breaking change affects downstream components.

For example: your Button component accepts variant and disabled - but the AI suggests isLoading because it saw that pattern elsewhere. No structured contract means no source of truth.

LogicStamp Context is a static analyzer that extracts deterministic component contracts from TypeScript - giving AI assistants structured architectural context instead of raw source code.

These contracts:

Stay in sync with your code (watch mode auto-regenerates)
Expose what matters (props, hooks, dependencies) without implementation noise
Work with any MCP-compatible AI assistant (Claude, Cursor, etc.)

Context bundles generated and consumed across MCP-powered AI workflows.

Same code ⇒ same context output. Diff outputs to detect architectural drift.

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

Quick Start

Try it in 30 seconds (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

For a complete setup (recommended):

npm install -g logicstamp-context
stamp init        # sets up .gitignore, scans for secrets
stamp context

ℹ️ Note: With npx, run npx logicstamp-context context. After global install, use stamp context.

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

Why Structured Context?

Without LogicStamp Context	With LogicStamp Context
AI parses 200 lines of implementation to infer a component's interface	AI reads a 20-line interface contract
Props/hooks inferred (often wrong)	Props/hooks explicit and verified
No way to know if context is stale	Watch mode catches changes in real-time
Different prompts = different understanding	Deterministic: same code = same contract
Manual context gathering: "Here's my Button component..."	Structured contracts: AI understands architecture automatically

The key insight: AI assistants don't need your implementation - they need your interfaces. LogicStamp Context extracts what matters and discards the noise.

What "Structured" Means

Instead of shipping 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.

⚡ Features

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

Watch Mode

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

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

Strict watch catches breaking changes that affect consumers:

Violation	Example
`breaking_change_prop_removed`	Removed `disabled` prop from Button
`breaking_change_event_removed`	Removed `onSubmit` callback
`breaking_change_function_removed`	Deleted exported `formatDate()`
`contract_removed`	Deleted entire component

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.

⚠️ Note: Context files are gitignored by default. For CI-based drift detection, the --baseline git:<ref> option (e.g., --baseline git:main) is not yet implemented. Until automation is available, use the manual workflow: generate context from current code, checkout baseline branch, generate context from baseline, then compare. See the roadmap for planned automation.

How it Works

Scan - Finds all .ts and .tsx files in your project
Analyze - Parses components and APIs using TypeScript AST (Abstract Syntax Tree) via ts-morph
Extract - Builds contracts with props, hooks, state, signatures
Graph - Creates dependency graph showing relationships
Bundle - Packages context optimized for AI workflows
Organize - Groups by folder, writes context.json files
Index - Creates context_main.json with metadata and statistics

Why AST parsing matters: Unlike text-based parsing (regex, string matching), AST parsing understands TypeScript's syntax structure, type information, and code semantics. This enables LogicStamp Context to accurately extract prop types, detect hooks, understand component composition, and handle complex patterns reliably - making contracts deterministic and trustworthy.

No pre-compilation needed. One command.

💡Tip: Use stamp context for basic contracts. Use stamp context style when you need style metadata (Tailwind classes, SCSS selectors, layout patterns).

📋 What LogicStamp Context Is (and Isn't)

LogicStamp Context IS:

✅ An AST-based static analysis tool - Uses the TypeScript compiler API (via ts-morph) to extract component contracts, props, hooks, and dependencies in a deterministic, type-aware way.

✅ A deterministic context generator - Produces structured architectural contract bundles for tooling and AI workflows.

✅ Local and offline-first - Runs entirely on your machine (no cloud services, no network calls).

✅ Framework-aware - Understands React, Next.js, Vue, Express, and NestJS patterns and extracts relevant metadata.

✅ Non-opinionated - Describes what exists without enforcing patterns or architectural decisions.

LogicStamp Context IS NOT:

❌ A code generator - It never writes or modifies your source code.

❌ A documentation generator - It produces structured contracts, not documentation.

❌ A build or runtime tool - It analyzes static source code only; it does not execute or bundle your application.

❌ A linter, formatter, or testing framework - It does not check code quality or run tests.

❌ An AI behavior controller - It provides structured context; it does not alter AI responses.

❌ A replacement for reading code - It accelerates understanding without replacing engineering judgment.

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 MCP Getting Started Guide for setup instructions.

Example Output

LogicStamp Context generates structured JSON bundles organized by folder:

{
  "type": "LogicStampBundle",
  "entryId": "src/components/Button.tsx",
  "graph": {
    "nodes": [
      {
        "entryId": "src/components/Button.tsx",
        "contract": {
          "kind": "react:component",
          "interface": {
            "props": {
              "variant": { "type": "literal-union", "literals": ["primary", "secondary"] },
              "onClick": { "type": "function", "signature": "() => void" }
            }
          },
          "composition": {
            "hooks": ["useState"],
            "components": ["./Icon"]
          }
        }
      }
    ],
    "edges": [["src/components/Button.tsx", "./Icon"]]
  }
}

📋 See docs/schema.md for complete format documentation.

Installation

npm install -g logicstamp-context

After installation, the stamp command is available globally.

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 generation
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

💻 CLI Usage Reference

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
stamp context --watch              # Watch mode
stamp context --watch --strict-watch  # Watch with breaking change detection
stamp context compare              # Detect changes vs existing context
stamp context validate [file]      # Validate context files
stamp context clean [path]         # Remove generated files

Common Options

Option	Description
`--depth <n>`	Dependency traversal depth (default: 2)
`--include-code <mode>`	Code inclusion: `none\|header\|full` (default: header)
`--include-style`	Extract style metadata (Tailwind, SCSS, animations)
`--format <fmt>`	Output format: `json\|pretty\|ndjson\|toon` (default: json)
`--max-nodes <n>`	Maximum nodes per bundle (default: 100)
`--profile <p>`	Preset: `llm-chat`, `llm-safe`, `ci-strict`, `watch-fast`
`--compare-modes`	Show token cost comparison across all modes
`--stats`	Emit JSON stats with token estimates
`--out <path>`	Output directory
`--quiet`	Suppress verbose output
`--strict-missing`	Exit with error if any missing dependencies found (CI-friendly)
`--debug`	Show detailed hash info (watch mode)
`--log-file`	Write change logs to `.logicstamp/` (watch mode)

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

Framework Support

Framework	Support Level	What's Extracted
React	Full	Components, hooks, props, styles
Next.js	Full	App Router roles, segment paths, metadata
Vue 3	Partial	Composition API (TS/TSX only, not .vue SFC)
Express.js	Full	Routes, middleware, API signatures
NestJS	Full	Controllers, decorators, API signatures
UI Libraries	Full	Material UI, ShadCN, Radix, Tailwind, Styled Components, SCSS, Chakra UI, Ant Design (component usage, props, composition; not raw CSS)

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

Documentation

Full documentation at logicstamp.dev/docs

Known Limitations

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

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

Requirements

Node.js >= 18.18.0 (Node 20+ recommended)
TypeScript codebase (React, Next.js, Vue (TS/TSX), Express, or NestJS)

Need Help?

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

License

MIT

Branding & Attribution

Contributing

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

This project follows a Code of Conduct.

Links: Website · GitHub · MCP Server · Changelog

Name		Name	Last commit message	Last commit date
Latest commit History 72 Commits
.github		.github
assets		assets
docs		docs
examples		examples
schema		schema
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LLM_CONTEXT.md		LLM_CONTEXT.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Structured context for AI coding assistants.

The Problem

Quick Start

Why Structured Context?

What "Structured" Means

⚡ Features

Watch Mode

One-time Comparison

How it Works

MCP Server

Example Output

Installation

Security

Usage

Common Options

Framework Support

Documentation

Known Limitations

Requirements

Need Help?

License

About

Uh oh!

Releases 28

Packages

Uh oh!

Contributors 2

Uh oh!

Languages

License

LogicStamp/logicstamp-context

Folders and files

Latest commit

History

Repository files navigation

Structured context for AI coding assistants.

The Problem

Quick Start

Why Structured Context?

What "Structured" Means

⚡ Features

Watch Mode

One-time Comparison

How it Works

MCP Server

Example Output

Installation

Security

Usage

Common Options

Framework Support

Documentation

Known Limitations

Requirements

Need Help?

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 28

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages