Signalint

Signalint

[CI] [npm version] [License: MIT] [Node.js]

Signalint is a reliable, read-only-by-default diagnostic intelligence layer for AI coding agents (Claude Code, Cursor, Codex, VS Code) and CI workflows.

Instead of flooding an agent's context window with thousands of raw compiler lines, Signalint normalizes diagnostics across compilers, linters, and language servers into bounded, priority-clustered issue summaries, calculates verification deltas against explicit baselines, and detects oscillating fix loops.

Key Differentiators

• 13 Complete MCP Tools: From incremental checks and immutable snapshots to live diagnostic ingestion and journaled transactional fix application.
• Verification Deltas: Exact arithmetic on introduced, resolved, and unchanged diagnostics with semantic identity matching that survives line shifts.
• Immutable Snapshots & Concurrency Safety: Isolated in-memory snapshot store keyed by checkId eliminates race collisions during concurrent checks.
• Monorepo-Aware Planning: Unites package manifests (pnpm-workspace.yaml) parsed via pure-JS YAML with glob negation exclusions and TypeScript Project References, ordering checks topologically.
• Multi-Source Provenance: Distinguishes compiler, linter, and editor/LSP diagnostics across JavaScript, TypeScript, Python (Ruff/Mypy), Rust (Clippy), and Go (GolangCI-Lint).
• Portable Host Hooks: Native verify-after-change adapters for Claude Code, Cursor, Codex, and VS Code.
• In-Memory Previews & In-Process Rollback: In-memory previews never touch disk; apply uses per-file adjacent temporary-file replacement, pre-write drift detection, and in-process best-effort rollback for multi-file writes (does not claim persistent crash recovery if aborted abruptly).

Quick Start

1. Requirements

• Node.js >= 22.12.0 (utilizes native node:sqlite).
• Your project installs its own diagnostic engines (typescript, oxlint, eslint, and/or @biomejs/biome). Signalint detects project-local installations and ships no bundled engines.

2. Initialize in your repository

npx signalint init

This detects your project's linters/compilers, generates signalint.config.json, and configures your installed MCP clients.

3. Add to MCP Clients

Add Signalint to your MCP configuration (e.g. claude_desktop_config.json, .cursor/mcp.json):

{  "mcpServers": {    "signalint": {      "command": "npx",      "args": ["-y", "signalint-mcp"]    }  }}

Complete MCP Tools Catalog

Signalint exposes 13 strictly typed MCP tools over stdio:

See docs/mcp-contract.md for full JSON Schemas and error codes.

CLI Commands

Signalint includes a comprehensive command-line interface:

# Run a project diagnostic scan:npx signalint check .npx signalint check src/ --format github    # GitHub Actions annotations
# View session statistics and cache economics:npx signalint stats
# Verify local engine availability and configuration:npx signalint doctor
# Manage host verify-after-change hooks:npx signalint hooks preview --runtime claudenpx signalint hooks install --runtime cursor --confirmnpx signalint hooks run --runtime claude --payload '<json-event>'

Monorepo Support

Signalint natively understands multi-package monorepos:

• Configure "monorepoMode": "auto" in signalint.config.json to detect pnpm-workspace.yaml via pure-JS YAML parsing with glob negation exclusions (!).
• Strictly differentiates local workspace packages (workspace:*) from external npm registry dependencies.
• Builds a topological dependency graph uniting package manifests and TypeScript project references.
• Caches whole-program TypeScript builds in isolated per-package directories (.signalint/cache/tsc/<project-id>/).
• Changes to a shared package automatically invalidate dependent packages while keeping independent siblings cached.

See docs/monorepo.md for configuration and architecture.

Verify-After-Change Hooks

Automate post-edit verification without creating infinite agent loops:

• Native adapters for Claude Code, Cursor, Codex, and VS Code.
• Emits bounded context into prompt windows and blocks only on unresolved syntax/type errors.

See docs/hooks.md for setup instructions.

Documentation Index

• Architecture & Subsystems
• MCP Protocol Contract & Schemas
• Host Hook Adapters Guide
• Monorepo Planning & Incremental TypeScript
• Known Limitations & Risk Register
• Wire Reduction Benchmarks
• Security & Threat Model

License

MIT © 2026 Tran Trong Qui