logicstamp-context

v0.3.7

Published

2 hours ago

Generate structured, deterministic, AI-ready context bundles via static analysis of TypeScript and React codebases

0High
0Medium
0Low

react typescript ai llm context documentation logicstamp claude chatgpt codebase-analysis ast static-analysis mcp ai-context code-context

LogicStamp Context

A CLI for context engineering that statically analyzes TypeScript codebases and produces structured context bundles for AI and CI.

Fast. Deterministic. One-time setup.

LogicStamp Context in action Sample stamp context output with generated bundles

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.

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

What you'll get:

📁 context.json files (one per folder with components, preserving your directory structure)
📋 context_main.json index file with project overview and folder metadata
All files written to current directory (or use --out <path> to specify a different location)

For a complete setup (recommended):

npm install -g logicstamp-context
stamp init        # security scan by default
stamp context

💡 First time? Run stamp init to set up .gitignore patterns and scan for secrets. You can skip this step, but it's recommended to prevent committing generated files and detect secrets.

ℹ️ If you see "PRIVATE_DATA" in output, see the Security section below.

Note: This is a beta release (v0.3.7). We're actively improving the tool based on user feedback. If you encounter any issues or have suggestions, please open an issue on GitHub.

📋 For a detailed step-by-step getting started guide with integration examples, see Getting Started Guide.

Why LogicStamp?

LLMs can reason about your project structure without scanning raw source files.

Structured Data vs Raw Source

Instead of parsing raw source code line-by-line, LogicStamp provides pre-processed, categorized information that's immediately actionable:

Semantic density - Information is grouped by meaning (layout, colors, spacing) rather than scattered in code
Pre-processed relationships - Dependency graphs are explicit (graph.edges) rather than requiring inference
Contract-based APIs - Component interfaces (logicSignature.props) are explicit, no need to read implementation
Categorized metadata - Style patterns, dependencies, and structure are organized for direct querying

Example: To answer "What design patterns does the Hero component use?":

Raw source: Read 200+ lines, parse className strings, identify patterns manually
Structured: Read style.layout.hasHeroPattern: true, style.visual.colors: [...] - answer in seconds

This transforms code analysis from "parse and infer" to "read and reason" - making AI assistants faster and more accurate.

Additional Benefits

Token efficient - Structured context replaces the need to ship raw source (varies by technology)
- When including style metadata (--include-style), token savings differ by framework:
  - CSS / SCSS / CSS Modules / styled-components: typically ~40-70% fewer tokens than raw styles
  - Tailwind CSS: typically ~5-10% fewer tokens (utility classes are already compact)
- Observed during beta testing; actual results vary by project structure and usage
Token savings are a side effect - the primary gain is deterministic, inspectable context.
Deterministic, structured contracts - Help AI avoid hallucinations by only referencing the true architecture
🔒 Built-in security - Automatic secret detection and sanitization in generated context files
Perfect for Cursor/Claude/GitHub Copilot Chat - Share context files for instant codebase understanding
CI-friendly - Detect drift, validate bundles, track changes

Framework Support

React - full support (components, hooks, props, styles)
Next.js - partial support (App / Pages Router analysis)
Vue 3 - partial support (Composition API in TS/TSX files)
UI frameworks - Material UI, ShadCN/UI, Radix UI, Tailwind CSS, Styled Components, SCSS/CSS Modules

Note: LogicStamp currently analyzes .ts and .tsx files only. JavaScript files (.js, .jsx) are not analyzed for context generation. Vue 3 support works with .ts/.tsx files only, not .vue SFC files. CSS and SCSS files imported by your TypeScript/TSX files are also parsed when using --include-style (standalone CSS/SCSS files that aren't imported won't be analyzed).

⚡ Features

AI-ready bundles - predictable, structured, deterministic
React/Next.js/Vue/TypeScript awareness - props, hooks/composables, state, deps
Style metadata - (Tailwind, SCSS, MUI, shadcn)
Next.js App Router detection - (client/server, layout/page/etc)
Vue 3 Composition API - (ref, reactive, computed, composables)
Dependency graph - (imports, cycles, missing deps)
Per-folder bundles - organized by your project structure
CI validation - (drift detection, schema validation)
Accurate token estimates - (GPT/Claude)
Security-first - automatic secret detection and sanitization
Fast, one-time setup - works out of the box (no config files needed, sensible defaults)
MCP-ready - AI agents can consume context bundles via a standardized MCP interface

How it Works

Scan: Finds all .ts and .tsx files in your project
Analyze: Parses React/Next.js/Vue components using TypeScript AST
Extract: Builds component contracts with structure and signatures
Graph: Creates dependency graph showing relationships
Bundle: Packages context bundles optimized for AI consumption
Organize: Groups bundles by folder and writes context.json files maintaining directory structure
Index: Creates context_main.json index with folder metadata and summary statistics

All in one command, no pre-compilation needed!

💡 Tip: Use stamp context for basic context generation (component contracts, dependencies, props). Use stamp context style (equivalent to stamp context --include-style) when you need style metadata extracted (Tailwind classes, SCSS selectors, CSS-in-JS patterns, layout information). Style extraction adds more tokens but provides richer design system context for AI assistants.

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 to analyze your project.

LogicStamp MCP Workflow MCP server calling the CLI to generate and consume context bundles

📋 See MCP Getting Started Guide for detailed installation instructions for Claude Code, Claude Desktop, Cursor, and other MCP clients.

Example Output

LogicStamp Context generates structured JSON bundles organized by folder. Each bundle contains a dependency graph with component contracts:

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

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

Installation

npm install -g logicstamp-context

After installation, the stamp command will be available globally.

Note: "Global CLI" means the tool is installed globally on your system (via npm install -g), making the stamp command available from any directory in your terminal, not just within a specific project folder.

Local install: npm install logicstamp-context → only available in that project
Global install: npm install -g logicstamp-context → available everywhere via stamp command

Security

Automatic Secret Protection (v0.3.0+)

LogicStamp Context automatically protects sensitive data in generated context files:

Security scanning by default - stamp init automatically scans for secrets (API keys, passwords, tokens)
Automatic sanitization - Detected secrets are replaced with "PRIVATE_DATA" in generated context files (source files are never modified)
Manual exclusions - Use stamp ignore <file> to manually exclude files with secrets from context generation via .stampignore
Safe by default - Only metadata is included in default modes; credentials only appear in --include-code full mode

⚠️ Seeing "PRIVATE_DATA" in your context files? This means secrets were detected in your codebase during scanning. The security scan examines .ts, .tsx, .js, .jsx, and .json files for secret patterns. Action required:
Review stamp_security_report.json to see what was found
Remove hard-coded secrets from your source code
Use environment variables or secret management tools instead
Run stamp ignore <file> to exclude files with secrets from context generation
Best practice: Never commit secrets to version control. Use .env files (in .gitignore) or secret management services.

ℹ️ Important: Always review generated context files before sharing. For complete security documentation, see SECURITY.md.

Usage

stamp --version                    # Show version number
stamp --help                       # Show help
stamp init [path] [options]        # Initialize project preferences (security scan runs by default)
stamp init --no-secure             # Initialize without security scan
stamp ignore <path> [path2] ...    # Add files/folders to .stampignore
stamp security scan [path] [options]  # Scan for secrets (API keys, passwords, tokens)
stamp context [path] [options]     # Generate context bundles
stamp context style [path] [options]  # Generate with style metadata
stamp context compare [options]    # Detect context drift
stamp context validate [file]      # Validate context files
stamp context clean [path] [options]  # Remove generated files

Quick Command Reference

| Command | Description | Docs | |---------|-------------|------| | stamp init | Initialize project (.gitignore, LLM_CONTEXT.md, config) | init.md | | stamp ignore | Add files/folders to .stampignore to exclude from context | ignore.md | | stamp security scan | Scan for secrets (API keys, passwords, tokens) | security-scan.md | | stamp security --hard-reset | Reset security configuration (delete security report) | security-scan.md | | stamp context | Generate AI-ready context bundles organized by folder | context.md | | stamp context style | Generate context with style metadata (Tailwind, SCSS, etc.) | style.md | | stamp context compare | Compare context files to detect changes (CI-friendly) | compare.md | | stamp context validate | Validate context file schema and structure | validate.md | | stamp context clean | Remove all generated context artifacts | clean.md |

Common Options

stamp context options:

--depth <n> / -d - Dependency traversal depth (default: 2)
--include-code <mode> / -c - Code inclusion: none|header|full (default: header)
--include-style - Extract style metadata (Tailwind, SCSS, animations, layout)
--format <fmt> / -f - Output format: json|pretty|ndjson|toon (default: json)
--max-nodes <n> / -m - Maximum nodes per bundle (default: 100)
--profile <profile> - Preset: llm-chat (default), llm-safe, ci-strict
--compare-modes - Compare token costs across all modes (none/header/header+style/full)
--stats - Emit JSON stats with token estimates (CI-friendly)
--out <path> / -o - Output directory (default: current directory)
--quiet / -q - Suppress verbose output

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

Documentation

For full Documentation see: https://logicstamp.dev/docs

Getting Started Guide - Step-by-step installation and quick start guide
Usage Guide - Complete usage documentation with examples
Example Files - Complete example files (context.json, .stampignore, security reports)
Token Optimization - Understand token costs and savings
Mode Comparison - Detailed comparison across all modes
Output Format - Complete schema documentation
CI Integration - CI/CD workflows and validation
Troubleshooting - Common issues and solutions
UIF Contracts - Understanding component contracts
Roadmap - Planned features, improvements, and future enhancements

Known Limitations

LogicStamp Context is still in beta. A few edge cases are not fully supported yet.

See the full list here: docs/limitations.md

Need Help?

Open an issue → https://github.com/LogicStamp/logicstamp-context/issues
Join our roadmap → https://logicstamp.dev/roadmap

Requirements

Node.js >= 18.18.0 (Node 20+ recommended)
TypeScript codebase (React or Next.js)

License

MIT

Branding & Attribution

These assets may not be used for third-party branding, logos, or commercial identity without permission. They are included in this repository for documentation and non-commercial use within the LogicStamp ecosystem only.

Contributing

Issues and PRs welcome! This is an open-source project.

See CONTRIBUTING.md for detailed guidelines, including:

Branching strategy (feature → main, no develop branch)
Branch naming conventions (feature/*, fix/*, docs/*)
Commit message format (Conventional Commits)
Development workflow and best practices

Community

This project follows a Code of Conduct. By participating, you agree to uphold it.