Configuration

Signalint reads signalint.config.json in the checked project root. Create it with npx signalint-mcp init, then review the detected settings. Engine-native rules remain in their own files, such as tsconfig.json or eslint.config.js.

A complete example

{
  "engines": {
    "oxlint": true,
    "tsc": true,
    "biome": false,
    "eslint": false
  },
  "ignore": ["node_modules/**", "dist/**", ".signalint/**"],
  "timeoutsMs": {
    "oxlint": 30000,
    "tsc": 60000,
    "biome": 30000,
    "eslint": 30000
  },
  "mcpPayload": "both"
}

This example assumes a TypeScript project with a root tsconfig.json and the selected engines installed. Oxlint and TypeScript are optional peers in 1.2.1, not bundled runtime dependencies. Set tsc to false for a JavaScript project without that config.

Engine selection

Key	Accepted value	Omitted-key behavior
engines.oxlint	Boolean	Enabled
engines.tsc	Boolean	Enabled; requires TypeScript configuration
engines.biome	Boolean, or { "includeFormatter": boolean }	Disabled
engines.eslint	Boolean	Detected from a root flat ESLint config when loading a project

init chooses settings based on detected tools, so its generated configuration may differ from these parser defaults. Set each engine explicitly if you need predictable behavior across repositories.

Include Biome formatter diagnostics

Biome lint diagnostics are enabled by true. Formatter diagnostics are suppressed unless you opt in:

{
  "engines": {
    "oxlint": false,
    "tsc": true,
    "biome": { "includeFormatter": true },
    "eslint": false
  }
}

Biome is an optional peer dependency. For this documented release, install the optional peer @biomejs/biome@2.5.15 before enabling it. Clear the diagnostic cache after changing includeFormatter: v1 does not hash this setting, so existing hits can retain the old behavior.

ESLint needs a project-local installation and a flat config; see diagnostic engines.

MCP payload mode

mcpPayload accepts "both" (default), "text", or "structured". A non-empty SIGNALINT_MCP_PAYLOAD environment value overrides it; invalid names throw an error. Restart the server after changing transport mode.

This is independent of SIGNALINT_COMPACT=1, which abbreviates check keys and omits the check root. Read MCP payload modes before opting in: text mode omits structured data/output schemas, and structured mode needs host support.

Ignore paths

ignore accepts non-empty strings, interpreted against normalized project-relative paths. The built-in matcher handles a limited * / ** / ? syntax, not a full glob library. Prefer simple explicit directory prefixes such as src/generated/**; wildcard prefixes combined with a trailing /** can behave differently from standard glob libraries.

{
  "ignore": ["node_modules/**", "dist/**", ".signalint/**", "src/generated/**"]
}

An explicit array replaces the default array. The project walker still skips child entries named node_modules, .git, .signalint, and dist; changing this array does not remove that walker behavior. Preserve any default exclusions you still want. Diagnostics whose path contains a node_modules segment are also excluded independently of this setting.

TypeScript stays whole-program. Ignored paths do not trigger an incremental file check and their diagnostics are removed from the result, but the TypeScript compiler still receives the configured program. ignore is not a substitute for include and exclude in tsconfig.json.

Execution timeouts

Values in timeoutsMs must be positive integers, in milliseconds:

Engine	Default
Oxlint	30,000 ms
TypeScript	60,000 ms
Biome	30,000 ms
ESLint	30,000 ms

Signalint attempts to terminate a timed-out process tree; errors are logged and cleanup is best-effort. Its engine outcome becomes status: "error"; completed engines’ diagnostics remain available. A timeout does not mean the project is clean.

Project-root override

The MCP server normally uses the working directory chosen by your client. SIGNALINT_PROJECT_ROOT can explicitly select a project root when the client does not launch there. See multiple projects before using a fixed path in a shared configuration.

SIGNALINT_ALLOW_UNINITIALIZED=1 bypasses the MCP requirement for an existing signalint.config.json. It does not bypass the JS/TS marker check. Use this only deliberately; normal setup should run init.

Validation and cache changes

Unknown configuration keys, wrong value types, and invalid timeout values fail validation rather than being silently ignored.

Tracked engine-config changes invalidate related cache entries. Not every nested, extended, or dynamic config is recognized equally. Read the cache reference before assuming a configuration change is covered.

Workspace mode and state overrides

monorepoMode accepts off (default), auto, or strict. SIGNALINT_MONOREPO_MODE overrides it. Discovery uses a limited pnpm block-list parser, not full YAML/glob support; see monorepos.

The MCP server can use SIGNALINT_PROJECT_ROOT instead of its launch directory; verify the actual canonical root with ping. SIGNALINT_STATE_DIR redirects supported SQLite/session/project-mode TypeScript storage. Prefer absolute per-project state directories; the setting does not redirect every build-mode compiler artifact or provide an OS sandbox.