Skip to content

About

Diagnose before agents fix.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Lynx Doctor mascot wearing a doctor cap

Lynx Doctor

A health check for your Lynx project.
Find threading, API, and build issues. Get fix suggestions and repair prompts for your agent.

Documentation · Quickstart · Examples · Contributing · 中文

Node.js 22.12+ Apache License 2.0

Choose a workflow

The lynx doctor inspecting code with a magnifying glass

Check your code →
Find issues and the exact lines to fix.

The lynx doctor holding a repair checklist

Work with an agent →
Turn the report into a repair prompt.

The lynx doctor checking a three-step workflow

Check pull requests →
Run the checks in GitHub Actions.

Quick Start

Requires Node.js 22.12 or later. Run a scan from your Lynx project root:

npx lynx-doctor@latest

Scan only changed files:

npx lynx-doctor@latest --diff

Fix with an Agent

Generate a prompt with source locations, fix suggestions, and verification commands:

npx lynx-doctor@latest --diff --agent-prompt

If you have a local coding agent set up, pass the prompt to it directly:

npx lynx-doctor@latest --diff --agent codex

When a scan finds issues in an interactive terminal, you can also choose an agent from the menu. See the agent guide for details.

Successful handoffs are verified by Doctor; the new report determines the exit status. Staged checks still require reviewed fixes to be staged. Handoffs use text output; run JSON/score modes separately.

Add to CI

Run this once in your project:

npx lynx-doctor@latest install

This adds a doctor script, a GitHub Actions workflow, and .agents/lynx-doctor.md with instructions for coding agents. The default workflow checks changed files on pull requests and fails on errors or warnings. See CI setup to adjust that behavior.

The installer pins the running version in an executable npx script, preserves existing setup, and places monorepo workflows at the Git root. Preview changes with install --dry-run.

What It Checks

Area Examples
reactlynx Thread boundaries, lifecycle hooks, main-thread handlers, globalPropsMode, lazy loading, TypeScript setup, native element contracts, and component library entries
lynx-ui Component imports, supported props, and gesture configuration
rspeedy Bundle-size risks such as re-exporting every module with export * and using eval()
lynx-css CSS property/feature support by rendering backend and minimum Lynx engine version

List rules:

npx lynx-doctor@latest rules list

Explain one rule:

npx lynx-doctor@latest rules explain reactlynx/background-only-api
CLI options, configuration, and Node API

CLI options

lynx-doctor [directory] [options]
Option Description
--verbose Show every diagnostic with source context, docs, and skill source
--json Output a structured scan report
--score Print only the numeric health score
--diff [base] Scan files changed against a base ref
--staged Read source from the Git index
--package Check existing component library runtime/declaration entry files after building
--category <category> Show one category, repeatable: reactlynx, lynx-ui, rspeedy, or lynx-css
--no-warnings Hide warning-severity diagnostics
--blocking <level> Fail threshold: error, warning, or none
--agent-prompt Print a focused agent repair prompt
--agent [command] Launch an agent and verify its changes; defaults to configured command or Codex
--no-agent-select Disable the interactive agent selection prompt

See the CLI reference for command details.

Configuration

Create lynx-doctor.config.ts, lynx-doctor.config.mjs, or lynx-doctor.config.json in the project root.

import { defineConfig } from "lynx-doctor";

export default defineConfig({
  targets: { android: "3.5", ios: "3.6" },
  ignore: {
    files: ["src/generated/**"]
  },
  rules: {
    "reactlynx/lazy-without-suspense": "warning"
  },
  categories: {
    "lynx-ui": "off"
  },
  agent: {
    command: "codex"
  }
});

targets uses Lynx engine versions, independently of the ReactLynx npm version. CSS checks are opt-in and leave missing data unknown. Reports expose scope, cssCoverage, and notices; a numeric score is not a coverage guarantee. agent.command is used only with explicit bare --agent.

Node API

import { buildAgentPrompt, formatReport, scanProject } from "lynx-doctor";

const report = await scanProject({
  directory: process.cwd(),
  diff: true,
  blocking: "warning"
});

console.log(formatReport(report, { verbose: true }));
console.log(buildAgentPrompt(report));

Examples

The repository includes standalone Lynx projects under examples/.

Project Purpose
healthy-shop A passing example with a score of 100/100
threading-regressions Intentional threading, lifecycle, and event errors
event-mode-settings Configuration and lazy-loading warnings

See CONTRIBUTING.md for local development, docs, and example validation.

License

Apache License 2.0

About

Diagnose before agents fix.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages