Signalint

Signalint

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:

Tool	Category	Safety Annotation	Description
ping	Diagnostics	Read-only (idempotent)	Verifies server responsiveness and canonical project root path.
check_project	Diagnostics	Read-only (idempotent)	Full project/workspace scan across all enabled engines.
check_files	Diagnostics	Read-only (idempotent)	Fast incremental check on specific files using content-hash caching.
get_issue_detail	Diagnostics	Read-only (idempotent)	Retrieves full, unomitted issue records anchored to an immutable checkId.
get_loop_status	Diagnostics	Read-only (idempotent)	Returns oscillating fix signatures and rule churn detected in the session.
get_diagnostic_snapshot	Snapshots	Read-only (idempotent)	Retrieves complete state and metrics for an immutable check snapshot.
compare_diagnostics	Deltas	Read-only (idempotent)	Computes verification delta between a baseline check and a current check.
after_edit_check	Deltas	Read-only (idempotent)	Runs incremental check on edited files and diffs against a baseline check.
ingest_diagnostics	Live / LSP	Read-only (openWorld: false)	Ingests external LSP or compiler diagnostics into Signalint's clustering model.
get_live_diagnostics	Live / LSP	Read-only (idempotent)	Returns active buffered diagnostics with source provenance.
preview_diagnostic_fix	Transactions	Read-only (destructive: false)	Stages proposed code fixes in-memory. Does not write to disk.
apply_diagnostic_fix	Transactions	Mutating (destructive: true)	Per-file adjacent temp replacement, pre-write drift check, and in-process best-effort rollback.
discard_diagnostic_fix	Transactions	Read-only (idempotent)	Drops an in-memory fix transaction without touching disk.

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 claude
npx signalint hooks install --runtime cursor --confirm
npx 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