Skip to content
Back to search

alint

🤖🤮 Hate the yuck codes that agents generated? Try `alint`, a ESLint like toolchain for intent driven code check, freeze your skills, AGENTS.md to lint rules

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alint-dev--alint/badge.svg)](/listings/alint-dev--alint)

HTML

<a href="/listings/alint-dev--alint"><img src="/api/listings/alint-dev--alint/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

`alint` is written in TypeScript and published as ESM packages for JavaScript and TypeScript projects. Release builds also include standalone binaries, so teams working in Python, Go, Rust, and other non-Node.js projects can run the CLI without setting up Node.js, npm, or pnpm.

You also need at least one OpenAI-compatible model provider. Local providers such as Ollama and LM Studio work well for repeated lint runs because they keep token cost predictable.

Install the CLI

Download a standalone binary from the GitHub release assets if you want to use `alint` without a Node.js toolchain.

Install globally if you want an `alint` command available everywhere:

npm install -g @alint-js/cli
pnpm add -g @alint-js/cli

Or install it in a project and run it through your package manager:

npm install -D @alint-js/cli
npx alint src
pnpm add -D @alint-js/cli
pnpm exec alint src

Configure a Model Provider

Use `alint setup` to write provider configuration. The `-N` flag is short for `--no-interactive`, so setup can run in scripts or through coding agents without opening an interactive TUI.

Without `--local`, setup writes the global config at `~/.config/alint/config.toml`. With `--local`, it writes `.alint/config.toml` in the current project.

Provider management commands use the same scope policy: writes target the global config by default, and `--local` selects the current project's config. Update an existing provider or edit individual fields with:

alint config providers update --provider openrouter
alint config providers set --provider openrouter endpoint https://openrouter.ai/api/v1
alint config providers set --provider openrouter headers.Authorization "Bearer $TOKEN"
alint config providers unset --provider openrouter headers.Authorization

`providers update` probes the provider and adds newly reported models. It is additive by default and does not automatically remove a configured model merely because the remote provider no longer reports it. In the interactive TUI, deselecting a configured model removes it when you confirm the update. Use the destructive `models prune` command when you intend to remove configured models absent from provider responses.

Provider inspection, command output, and failure reports show header names only; they never print header values. Header values supplied as command arguments may remain in shell history. Use an environment variable such as `$TOKEN`, not a literal credential.

<details> <summary>Ollama</summary>

alint setup -N \
  --provider-endpoint http://localhost:11434/v1 \
  --provider-model qwen:8b

</details>

Write provider setup into the current project when a repository should carry its own model mapping:

alint setup -N \
  --local \
  --provider-endpoint http://localhost:11434/v1 \
  --provider-model qwen:8b

<details> <summary>LM Studio</summary>

alint setup -N \
  --provider-endpoint http://localhost:1234/v1 \
  --provider-model qwen:8b

</details>

<details> <summary>OpenRouter</summary>

export OPENROUTER_API_KEY="sk-..."

alint setup -N \
  --provider-endpoint https://openrouter.ai/api/v1 \
  --provider-header "Authorization=Bearer $OPENROUTER_API_KEY" \
  --provider-header "HTTP-Referer=http://localhost" \
  --provider-header "X-OpenRouter-Title=alint" \
  --provider-model openrouter:fusion

</details>

<details> <summary>OpenAI</summary>

export OPENAI_API_KEY="sk-..."

alint setup -N \
  --provider-endpoint https://api.openai.com/v1 \
  --provider-header "Authorization=Bearer $OPENAI_API_KEY" \
  --provider-model gpt-5.4-mini

</details>

Run alint

Run the CLI against files or directories:

alint src
alint demo.ts
alint --format json demo.ts

--dirty

Use `--dirty` without file arguments to lint only existing files that differ from `HEAD`:

alint --dirty

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 771 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <picture>
  2. <source
  3. width="200"
  4. srcset="./docs/assets/alint-logo.svg"
  5. media="(prefers-color-scheme: dark)"
  6. />
  7. <source
  8. width="200"
  9. srcset="./docs/assets/alint-logo.svg"
  10. media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)"
  11. />
  12. <img width="200" src="./docs/assets/alint-logo.svg" alt="Alint Logo" />
  13. </picture>
  14. # `alint`
  15. [![npm version][npmx-version-src]][npmx-version-href]
  16. [![npm downloads][npmx-downloads-src]][npmx-downloads-href]
  17. [![bundle][bundle-src]][bundle-href]
  18. [![License][license-src]][license-href]
  19. [![JSDocs][jsdocs-src]][jsdocs-href]
  20. ![Demo](./docs/assets/demo.gif)
  21. `alint` is an [`eslint`](https://eslint.org/) inspired agentic code analysis tool for vibe-coded code that needs another look. It runs model-backed rules against source files, reports diagnostics in a familiar lint format, and lets rule authors use plain model calls or swappable tool-using agents when a rule needs deeper context.
  22. While `alint` is inspired by `eslint`, we expect the concept that `alint` brings to the table to be a new paradigm for code analysis. It should not be limited to just JavaScript/TypeScript. You can extend this to other languages, non-code artifacts, generated files, or any content a plugin knows how to review.
  23. <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  24. <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  25. ## Table of Contents
  26. - [Installation and Usage](#installation-and-usage)
  27. - [Concepts](#concepts)
  28. - [Packages](#packages)
  29. - [Documentation Automation](#documentation-automation)
  30. - [Development](#development)
  31. - [Status](#status)
  32. - [License](#license)
  33. <!-- END doctoc generated TOC please keep comment here to allow auto update -->
  34. ## Installation and Usage
  35. ### Prerequisites
  36. `alint` is written in TypeScript and published as ESM packages for JavaScript and TypeScript projects. Release builds also include standalone binaries, so teams working in Python, Go, Rust, and other non-Node.js projects can run the CLI without setting up Node.js, npm, or pnpm.
  37. You also need at least one OpenAI-compatible model provider. Local providers such as Ollama and LM Studio work well for repeated lint runs because they keep token cost predictable.
  38. ### Install the CLI
  39. Download a standalone binary from the GitHub release assets if you want to use `alint` without a Node.js toolchain.
  40. Install globally if you want an `alint` command available everywhere:
  41. ```bash
  42. npm install -g @alint-js/cli
  43. pnpm add -g @alint-js/cli
  44. ```
  45. Or install it in a project and run it through your package manager:
  46. ```bash
  47. npm install -D @alint-js/cli
  48. npx alint src
  49. ```
  50. ```bash
  51. pnpm add -D @alint-js/cli
  52. pnpm exec alint src
  53. ```
  54. ### Configure a Model Provider
  55. Use `alint setup` to write provider configuration. The `-N` flag is short for `--no-interactive`, so setup can run in scripts or through coding agents without opening an interactive TUI.
  56. Without `--local`, setup writes the global config at `~/.config/alint/config.toml`. With `--local`, it writes `.alint/config.toml` in the current project.
  57. Provider management commands use the same scope policy: writes target the global config by default, and `--local` selects the current project's config. Update an existing provider or edit individual fields with:
  58. ```bash
  59. alint config providers update --provider openrouter
  60. alint config providers set --provider openrouter endpoint https://openrouter.ai/api/v1
  61. alint config providers set --provider openrouter headers.Authorization "Bearer $TOKEN"
  62. alint config providers unset --provider openrouter headers.Authorization
  63. ```
  64. `providers update` probes the provider and adds newly reported models. It is additive by default and does not automatically remove a configured model merely because the remote provider no longer reports it. In the interactive TUI, deselecting a configured model removes it when you confirm the update. Use the destructive `models prune` command when you intend to remove configured models absent from provider responses.
  65. Provider inspection, command output, and failure reports show header names only; they never print header values. Header values supplied as command arguments may remain in shell history. Use an environment variable such as `$TOKEN`, not a literal credential.
  66. <details>
  67. <summary>Ollama</summary>
  68. ```bash
  69. alint setup -N \
  70. --provider-endpoint http://localhost:11434/v1 \
  71. --provider-model qwen:8b
  72. ```
  73. </details>
  74. Write provider setup into the current project when a repository should carry its own model mapping:
  75. ```bash
  76. alint setup -N \
  77. --local \
  78. --provider-endpoint http://localhost:11434/v1 \
  79. --provider-model qwen:8b
  80. ```
  81. <details>
  82. <summary>LM Studio</summary>
  83. ```bash
  84. alint setup -N \
  85. --provider-endpoint http://localhost:1234/v1 \
  86. --provider-model qwen:8b
  87. ```
  88. </details>
  89. <details>
  90. <summary>OpenRouter</summary>
  91. ```bash
  92. export OPENROUTER_API_KEY="sk-..."
  93. alint setup -N \
  94. --provider-endpoint https://openrouter.ai/api/v1 \
  95. --provider-header "Authorization=Bearer $OPENROUTER_API_KEY" \
  96. --provider-header "HTTP-Referer=http://localhost" \
  97. --provider-header "X-OpenRouter-Title=alint" \
  98. --provider-model openrouter:fusion
  99. ```
  100. </details>
  101. <details>
  102. <summary>OpenAI</summary>
  103. ```bash
  104. export OPENAI_API_KEY="sk-..."
  105. alint setup -N \
  106. --provider-endpoint https://api.openai.com/v1 \
  107. --provider-header "Authorization=Bearer $OPENAI_API_KEY" \
  108. --provider-model gpt-5.4-mini
  109. ```
  110. </details>
  111. ### Run alint
  112. Run the CLI against files or directories:
  113. ```bash
  114. alint src
  115. alint demo.ts
  116. alint --format json demo.ts
  117. ```
  118. #### --dirty
  119. Use `--dirty` without file arguments to lint only existing files that differ from `HEAD`:
  120. ```bash
  121. alint --dirty
  122. ```
  123. This includes staged, unstaged, and untracked files from the Git repository root. Ignored and deleted files are excluded. Registered submodule worktrees are excluded. A clean repository exits successfully without producing lint output.
  124. #### --model
  125. Override the matched model for a one-off run:
  126. ```bash
  127. alint --model qwen:8b demo.ts
  128. ```
  129. #### --lang
  130. When the project-local setup does not configure any models, model calls without a rule-level or call-level selector use the `default` alias from the global setup. Rule selectors continue to use normal model matching. Configuring at least one model in `.alint/config.toml` restores project-first matching for unselected calls. An explicit `--model` override always takes precedence.
  131. Ask model-backed rules to write diagnostics in a specific language:
  132. ```bash
  133. alint --lang zh-CN src
  134. ```
  135. #### --rule
  136. Run only the rules a filter names, to read one rule's findings without paying for every other rule in the run:
  137. ```bash
  138. alint --rule docs/review-copy src
  139. alint --rule 'docs/*' src
  140. alint --rule docs/review-copy,docs/naming src
  141. ```
  142. A pattern matches the configured rule id (`plugin/rule`) or the rule's own name. The flag is repeatable and accepts a comma-separated list. Filtered rules are left unplanned, so the run neither calls their models nor reports their diagnostics. When the filter matches no enabled rule, the run fails and lists the rule ids it did enable, because a silent empty run is indistinguishable from a clean one.
  143. `alint` returns exit code `0` when diagnostics contain no errors, including warning-only runs. It returns `1` when at least one error diagnostic is reported and `2` when the command cannot complete because of a configuration, input, or runtime failure. `alint output inspect` uses the same exit-code behavior for saved results.
  144. ### Inspect Configuration and Output
  145. Useful CLI commands:
  146. ```bash
  147. alint config inspect src/index.ts
  148. alint config providers list
  149. alint config providers show openrouter
  150. alint config models list
  151. alint config models show ollama/qwen
  152. alint config models probe --endpoint http://localhost:11434/v1
  153. alint config models rm qwen --provider ollama
  154. alint config models prune --provider ollama -N --yes
  155. ```
  156. When a model ID exists under multiple providers, qualify it as `<provider>/<model-id>` or pass `--provider <provider-id>`. Configuration mutations write globally unless `--local` selects the current project's setup config.
  157. `models rm` removes one exact configured model. `models prune` probes provider model endpoints and destructively removes configured IDs that are no longer reported. Interactive prune asks for confirmation; scripts must pass `-N --yes`.
  158. Save machine-readable output and inspect it later without rerunning model calls:
  159. ```bash
  160. alint --format json src > alint-output.json
  161. alint output inspect alint-output.json
  162. ```
  163. ### Editor Integration
  164. `alint lsp` runs alint as a language server on stdin and stdout. Any editor with LSP support can
  165. use it.
  166. The server is cache-first. It publishes diagnostics that earlier runs stored, and it never calls a
  167. model on its own, so opening a workspace costs nothing. A cold cache shows no diagnostics. Run
  168. `alint` once to fill it.
  169. Diagnostics appear when the editor opens the workspace. They refresh when you save a file, and when
  170. a file changes on disk outside the editor, for example after `git checkout`. The server reloads
  171. `alint.config.ts` after it changes. Changes on disk and config reloads need an editor that supports
  172. dynamic registration for `workspace/didChangeWatchedFiles`. The server opens and closes workspace
  173. folders as the editor adds and removes them.
  174. Configure the editor to start the command. In Neovim:
  175. ```lua
  176. vim.lsp.config.alint = {
  177. cmd = { 'alint', 'lsp' },
  178. root_markers = { 'alint.config.ts' },
  179. }
  180. ```
  181. The server declares three commands. `alint.runFile` and `alint.runWorkspace` start runs that call
  182. models and spend tokens; both report progress and accept cancellation. `alint.clearCache` deletes
  183. the cached diagnostics.
  184. #### VS Code
  185. The extension in `apps/vscode` starts the server and displays the diagnostics. It is not published
  186. to the Marketplace yet. To run it from a checkout:
  187. ```bash
  188. pnpm -F @alint-js/vscode build
  189. code --extensionDevelopmentPath=apps/vscode/dist /path/to/your/project
  190. ```
  191. The extension finds the alint executable in this order: the `alint.path` setting, then
  192. `node_modules/.bin/alint` in the workspace folder, then `PATH`. The workspace installation takes
  193. precedence, so the server and a terminal run use the same cache.
  194. ### Codex stop-gate plugin (optional)
  195. #### Install
  196. The Codex plugin adds a Stop hook that runs `alint --dirty` before the agent ends a turn.
  197. Run these commands to install the plugin from the repository's default branch. These commands do not select the latest release:
  198. ```bash
  199. codex plugin marketplace add moeru-ai/alint \
  200. --sparse .agents/plugins \
  201. --sparse plugins/codex-plugin-alint
  202. codex plugin add alint@alint
  203. ```
  204. To install from a release, use its Git tag:
  205. ```bash
  206. codex plugin marketplace add moeru-ai/alint \
  207. --ref vX.Y.Z \
  208. --sparse .agents/plugins \
  209. --sparse plugins/codex-plugin-alint
  210. codex plugin add alint@alint
  211. ```
  212. Replace `vX.Y.Z` with the required release tag. Review and trust the Stop hook when Codex asks. The plugin stays inactive until a repository enables Stop Gate.
  213. #### Configure
  214. The codex plugin explicitly requires per-repo enable. Use this command to enable for current repository:
  215. - .toml: run `alint config integrations stop-gate enable`
  216. - .js/.ts:
  217. ```typescript
  218. export default defineConfig([
  219. // ...
  220. {
  221. integrations: {
  222. stopGate: {
  223. enabled: true,
  224. // target: 'dirty-files' | 'all'
  225. // timeoutMs: 900000
  226. },
  227. },
  228. },
  229. // ...
  230. ])
  231. ```
  232. ## Concepts
  233. `alint` keeps the familiar lint shape: select targets, apply named rules, report diagnostics, and return an exit code that CI can understand. The difference is that a rule can reach its judgment through model calls or a tool-using agent when syntax-only checks are not enough.
  234. ### `alint` User side
  235. #### Configurations
  236. `alint` uses two configuration systems with separate schemas and responsibilities:
  237. | Configuration | Priority (high → low) | Content |
  238. | --- |--------------------------------------------------------------------------------------|----------------------------------------------------------------------|
  239. | Setup | Environment and CLI overrides > `.alint/config.toml` > `~/.config/alint/config.toml` | Providers, models, and runner defaults. |
  240. | Lint | Environment and CLI overrides > `alint.config.*` | Files, ignores, plugins, rules, and other project-level lint policy. |
  241. Use setup TOML for machine or project provider definitions:
  242. ```toml
  243. version = 1
  244. [[providers]]
  245. id = "http://localhost:11434/v1"
  246. type = "openai-compatible"
  247. endpoint = "http://localhost:11434/v1"
  248. [[providers.models]]
  249. id = "qwen:8b"
  250. name = "qwen:8b"
  251. size = "small"
  252. capabilities = [ "tool-call" ]
  253. [providers.models.default_params]
  254. thinking = { type = "disabled" }
  255. ```
  256. `default_params` is merged into every chat request for that model. Use it for provider-specific request fields that are not covered by the rest of the model entry.
  257. The CLI can also launch an ACP coding-agent command and expose it to rules as an ordinary model. Interactive `alint setup` provides presets for Claude Code, Codex, Gemini CLI, Kimi Code CLI, and OpenCode:
  258. ```toml
  259. version = 1
  260. [[providers]]
  261. id = "acp"
  262. [[providers.models]]
  263. id = "codex"
  264. name = "Codex ACP"
  265. driver = "acp"
  266. aliases = [ "default" ]
  267. capabilities = [ "tool-call" ]
  268. command = "codex-acp"
  269. args = []
  270. cwd = "."
  271. ```
  272. Then run `alint --model acp/codex src`. The checked-in `alint.config.ts` remains lint policy; process commands come only from global setup or `.alint/config.toml`. The command inherits the environment that launched `alint`; optional model `env` entries are literal overrides and should not contain committed credentials. Each concurrent request starts one ACP process, and request tools require MCP-over-HTTP support from the agent.
  273. `alint` structured output forces a tool call (`tool_choice`). Some models, such as DeepSeek V4, reject that combination while thinking/reasoning is enabled. For those models, set `thinking = { type = "disabled" }` as above so structured output can run.
  274. Note that `-N` stands for `--no-interactive`, which means this is not an interactive setup. TUI is not required, so you can ask Codex or Claude Code to run this command for you.
  275. You can also use `--local` to write the config in the current project:
  276. ```bash
  277. alint setup -N \
  278. --local \
  279. --provider-endpoint http://localhost:11434/v1 \
  280. --provider-model qwen:8b
  281. ```
  282. - Without `--local`, `alint` writes the global config under `~/.config/alint/config.toml`.
  283. - `--local` writes `.alint/config.toml` in the current project.
  284. - You can inspect configs using the `alint config` command group.
  285. ##### Codex Stop Gate
  286. Configure the optional Codex Stop Gate integration through the same project config system:
  287. ```bash
  288. alint config integrations stop-gate enable
  289. alint config integrations stop-gate show
  290. alint config integrations stop-gate set --target all --timeout-ms 1800000
  291. alint config integrations stop-gate disable
  292. ```
  293. Stop Gate is disabled by default and runs only when the repository explicitly sets `integrations.stopGate.enabled = true`. The defaults after activation are `target = "dirty-files"` and `timeoutMs = 900000`; the maximum timeout is `86100000` (23 hours 55 minutes), leaving five minutes inside the plugin's 24-hour Codex hook limit for startup and persistence. The writer persists only non-default overrides and only extends the existing TOML write path; it does not extend the config writer to other formats. Read the [`plugins/codex-plugin-alint`](https://github.com/moeru-ai/alint/tree/main/plugins/codex-plugin-alint) documentation for complete runtime behavior.
  294. #### Using Rules & Plugins
  295. Similar to `eslint`, use `alint.config.ts` for files, ignores, plugins, and rules:
  296. ```ts
  297. import { defineConfig } from '@alint-js/cli'
  298. import { examplePlugin } from '@alint-js/plugin-example'
  299. export default defineConfig([
  300. {
  301. files: ['**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}'],
  302. ignore: {
  303. // Reads applicable nested .gitignore files when selecting lint targets.
  304. // This is powered by gitignore-fs.
  305. gitignore: true,
  306. },
  307. plugins: {
  308. example: examplePlugin,
  309. },
  310. rules: {
  311. // The `example` prefix is the local alias configured above.
  312. 'example/inline-miniature-normalizer': 'warn',
  313. 'example/no-redundant-jsdoc': 'warn',
  314. 'example/no-trivial-wrapper-stack': 'warn',
  315. },
  316. },
  317. ])
  318. ```
  319. #### Nested configs
  320. Every `alint.config.*` below the repository root is loaded together with the root config, and each file is scoped to the directory that contains it:
  321. ```ts
  322. // packages/app/alint.config.ts
  323. import { defineConfig } from '@alint-js/cli'
  324. import { appPlugin } from './alint/plugin'
  325. export default defineConfig([
  326. {
  327. plugins: { app: appPlugin },
  328. rules: { 'app/layer-boundary': 'error' },
  329. },
  330. ])
  331. ```
  332. The item above reaches `packages/app/**` only. `files`, `directories`, and `ignores` resolve against the directory of the config that declares them, an item that declares no target patterns covers its whole subtree, and a deeper config overrides an outer one for its own directory. A package that owns a rule therefore needs one file, not an entry in the root config plus the same scope repeated in every tool that reads it.
  333. - Discovery skips hidden directories, `node_modules`, and build output (`build`, `coverage`, `dist`, `out`, `vendor`).
  334. - `--config <path>` pins exactly one config file and disables discovery, so a CI job can run one specific config.
  335. - Every config file shares one plugin alias namespace and one plugin lockfile, and `alint plugin install` installs the plugins nested configs declare. Two files that bind one alias to different specifiers fail the load instead of resolving silently to one of them.
  336. - Keep project-scoped rules (`onTargetProject`) in the root config: the project target sits outside a nested item's base path, so a nested config cannot claim it.
  337. #### Executable and static configs
  338. `alint` supports executable configs (`.js`, `.ts`, `.mjs`, `.cjs`, `.mts`, and `.cts`) and data-only static configs (`.toml`, `.yaml`, `.yml`, `.json`, `.jsonc`, and `.json5`).
  339. - Executable configs export a flat config array and can import plugin definitions directly.
  340. - Static configs use a `config.group` array and identify plugin sources with strings. They are useful for Python, Rust, Go, and other repositories that do not want to author a JavaScript config file or install a Node.js package manager just to run `alint`.
  341. For example, a TOML static config can install an exact remote package or a local plugin directory:
  342. ```toml
  343. [[config.group]]
  344. [config.group.plugins]
  345. plugin_1 = "@scope/alint-plugin-example1@1.2.3" # package
  346. plugin_2 = "./plugins/relative-plugin-examplex" # relative directory
  347. plugin_3 = "/opt/alint/plugins/absolute-plugin" # absolute directory
  348. ```
  349. Relative plugin paths are resolved from the directory containing the config file, including when `--config` points to a nested config. On Windows, use TOML literal strings to preserve native backslashes:
  350. ```toml
  351. [[config.group]]
  352. [config.group.plugins]
  353. native = 'C:\alint\plugins\native-plugin'
  354. ```
  355. Use `alint plugin install` after adding or changing plugin sources.
  356. - **Package:** `@scope/alint-plugin-example1@1.2.3` downloads that exact version into `.alint/plugins/store`, verifies its integrity, and loads its root export.
  357. - **Local:** `./plugins/my-plugin` or an absolute directory loads the current package root export in place. `alint` checks that the package and entry exist and that the entry stays inside the package directory. It does not build the plugin or install the plugin's dependencies.
  358. #### Declarative local rule plugins
  359. For simple prompt-backed rules, a local plugin directory can omit `package.json` and contain one or more `rule.alint.*` files:
  360. ```toml
  361. # rules/architecture/semantic/rule.alint.toml
  362. name = "semantic-boundary"
  363. builtInAgent = "basic-structured"
  364. instruction = """
  365. Find semantic boundary problems in the reviewed source.
  366. Report concrete findings with line numbers and short suggestions.
  367. """
  368. includeFiles = [ "src/**/*.py" ]
  369. excludeFiles = [
  370. "**/*_test.py",
  371. "**/vendor/**",
  372. ]
  373. ```
  374. Reference the directory through the same static `plugins` table:
  375. ```toml
  376. [[config.group]]
  377. files = [ "src/**/*.py" ]
  378. language = "plaintext"
  379. [config.group.plugins]
  380. arch = "./rules/architecture"
  381. [config.group.rules]
  382. "arch/semantic-boundary" = "warn"
  383. ```
  384. `name` becomes the local rule id. `builtInAgent` can be `basic-structured` for a prompt-only structured-output rule or `basic-coding-agent` for a small built-in agent with filesystem tools. `includeFiles` and `excludeFiles` define where diagnostics may be reported; they do not limit what `basic-coding-agent` can inspect.
  385. Editing a rule's `instruction`, `includeFiles`, or `excludeFiles` invalidates the findings it cached: a declarative rule declares those inputs as its cache key, so a changed rule text never replays stale findings.
  386. Run the install command again after changing a source string, moving a local directory, or changing its symlink target. Changes inside the same local directory are loaded by the next CLI process without reinstalling.
  387. Local plugins execute as trusted Node.js code. Directory containment checks validate the installed source; they are not a sandbox.
  388. #### Plugin lockfile
  389. `alint plugin install` writes `.alint/plugins/lock.json`. Package entries lock the downloaded package and integrity metadata. Local entries lock the physical directory identity while loading its current contents at runtime.
  390. Rule severities follow the familiar lint convention:
  391. - `"off"` or `0` disables a rule.
  392. - `"warn"` or `1` reports a warning.
  393. - `"error"` or `2` reports an error.
  394. Flat configs can analyze non-JavaScript files by selecting `plaintext`. Language ids follow [VS Code's language identifiers](https://code.visualstudio.com/docs/languages/identifiers), so a plugin that registers a language should use the same id:
  395. ```ts
  396. import docsPlugin from '@your-alint-config/docs-rules'
  397. import { defineConfig } from '@alint-js/cli'
  398. export default defineConfig([
  399. {
  400. files: ['docs/**/*.md', '**/*.txt'],
  401. language: 'plaintext',
  402. plugins: {
  403. docs: docsPlugin,
  404. },
  405. rules: {
  406. 'docs/review-copy': 'warn',
  407. },
  408. },
  409. ])
  410. ```
  411. #### Cache and Stats
  412. `alint` caches rule target results by default in `.alintcache` to avoid repeating LLM calls for unchanged source targets.
  413. After each cacheable rule job completes, `alint` writes a cache checkpoint before releasing that job's scheduler slot. Each checkpoint atomically replaces the complete cache file, so an interrupted run can reuse every result that had already become durable. Cache hits, skipped jobs, failed jobs, and rules that opt out of caching do not add checkpoint writes. Any checkpoint or final cache write error causes the run to fail.
  414. > [!NOTE]
  415. > `.alintcache` should not be committed to Git. Add it to `.gitignore` before running repeated local analysis.
  416. ```bash
  417. echo ".alintcache" >> .gitignore
  418. ```
  419. Disable cache for a single run:
  420. ```bash
  421. alint --no-cache src
  422. ```
  423. Run stats are recorded by default. Use `--no-stats` to skip recording for a run, and use the `stats` command group to inspect saved usage over time.
  424. ### Rule Developer side
  425. To reduce the token cost during analysis while allowing rule authors to specify model size and capabilities, `alint` allows rule authors to **Request & Match** models with *Capability Selector* and *Size Selector*, instead of hardening the entire `alint` run to use a single model for all rules.
  426. In other words, you could set up your DeepSeek, OpenAI, Ollama, or other OpenAI-compatible model on your machine and let rule authors request a model with `tool-call` capability and `small` size. `alint` will match the best configured model for them.
  427. ```ts
  428. const model = await ctx.model({
  429. capabilities: ['tool-call'],
  430. size: 'small',
  431. })
  432. ```
  433. You can also call `ctx.model()` without arguments when a rule does not need a specific size or capability.
  434. #### About agent
  435. In `alint`, we don't limit you to any specific agent SDK. You can use an exported client from a framework such as Eve, Strands, Pi, Claude Code SDK, Codex SDK, or another tool-using runtime to implement your own agent to analyze code.
  436. Agentic rules use `ctx.agent` when they need a multi-step tool loop, such as reading related files before reporting findings. The rule stays framework-agnostic, and the user chooses the adapter:
  437. ```ts
  438. import { createApeiraAdapter } from '@alint-js/agent-apeira'
  439. import { createAgentExamplePlugin } from '@alint-js/plugin-example-agent'
  440. export default [
  441. {
  442. agent: createApeiraAdapter(),
  443. extends: ['agent-example/recommended'],
  444. plugins: {
  445. 'agent-example': createAgentExamplePlugin(),
  446. },
  447. },
  448. ]
  449. ```
  450. Current adapter packages include:
  451. - `@alint-js/agent-apeira` for Apeira on the xsai stack.
  452. - `@alint-js/agent-pi` for Pi.
  453. However, be careful with token cost. `alint` is designed to be a code analysis tool, where rapid and repeated calls to the model are expected. Local models, cheap small models, and cache-friendly prompts are usually better defaults than routing every rule target through a large hosted model.
  454. #### BYOA, any agent works
  455. Bring Your Own Agent means `alint` does not try to own the agent harness. A rule can depend on the `@alint-js/core` agent contract, while the actual runtime can be Apeira, Pi, your own in-house agent, or a small function that calls the tools you need.
  456. If an adapter is missing, you can implement the missing function or package your own plugin to replace it. The important part is that the rule reports diagnostics back through `alint`; how the agent reads files, calls tools, plans steps, or talks to a model is intentionally left to the adapter or plugin author.
  457. #### Example rule
  458. Rules are ordinary JavaScript objects built with the public DSL from `@alint-js/core`. A rule receives source targets and reports diagnostics.
  459. ```ts
  460. import { defineRule } from '@alint-js/core'
  461. export const checkFunctionRule = defineRule({
  462. create: ctx => ({
  463. async onTargetFunction(target) {
  464. const model = await ctx.model({
  465. capabilities: ['tool-call'],
  466. size: 'small'
  467. })
  468. ctx.report({
  469. filePath: target.file.path,
  470. loc: target.loc,
  471. message: `checked ${target.name} with ${model.id}`,
  472. })
  473. },
  474. }),
  475. })
  476. ```
  477. Package rules as plugins:
  478. ```ts
  479. import { definePlugin } from '@alint-js/core'
  480. import { checkFunctionRule } from './rules/check-function'
  481. export default definePlugin({
  482. configs: {
  483. recommended: [
  484. {
  485. rules: {
  486. 'my-plugin/check-function': 'warn',
  487. },
  488. },
  489. ],
  490. },
  491. rules: {
  492. 'check-function': checkFunctionRule,
  493. },
  494. })
  495. ```
  496. Rule authors can opt out of caching when a rule depends on external state:
  497. ```ts
  498. defineRule({
  499. cache: false,
  500. create: ctx => ({
  501. onTargetFile(target) {
  502. // Always reruns.
  503. },
  504. }),
  505. })
  506. ```
  507. Rules whose findings depend on inputs their source does not show must declare those inputs as `cacheKey`: an imported prompt, a shared message builder, or the text of a preset that builds the rule. `alint` hashes the rule source and `cacheKey` into every cache entry:
  508. ```ts
  509. import prompt from './prompt.md?raw'
  510. defineRule({
  511. cacheKey: { agentVersion: 1, prompt },
  512. create: ctx => ({ /* ... */ }),
  513. })
  514. ```
  515. Without a cache key, editing the prompt changes what the rule asks the model while the cache entry stays valid, and the next run replays the previous findings as cache hits without running the rule at all.
  516. ## Packages
  517. | Package | Purpose |
  518. | --- | --- |
  519. | [`@alint-js/cli`](https://github.com/moeru-ai/alint/tree/main/packages/cli) | CLI entrypoint, user-facing config facade, setup commands, reporters, output inspection, and stats commands. |
  520. | [`@alint-js/config`](https://github.com/moeru-ai/alint/tree/main/packages/config) | Lower-level config loading, setup TOML parsing, config paths, and ignore defaults for tools. |
  521. | [`@alint-js/core`](https://github.com/moeru-ai/alint/tree/main/packages/core) | SDK and run engine for plugins, rules, source runtime, model resolution, diagnostics, cache, and agent contracts. |
  522. | [`@alint-js/agent-apeira`](https://github.com/moeru-ai/alint/tree/main/packages/agent-apeira) | Apeira-backed `AgentAdapter`. |
  523. | [`@alint-js/agent-pi`](https://github.com/moeru-ai/alint/tree/main/packages/agent-pi) | Pi-backed `AgentAdapter`. |
  524. | [`@alint-js/languages`](https://github.com/moeru-ai/alint/tree/main/packages/languages) | First-party language support beyond core's built-in JavaScript and TypeScript: Go, Python, and Rust. |
  525. | [`@alint-js/plugin-example`](https://github.com/moeru-ai/alint/tree/main/packages/plugin-example) | Example TypeScript/JavaScript model-backed rules. |
  526. | [`@alint-js/plugin-example-agent`](https://github.com/moeru-ai/alint/tree/main/packages/plugin-example-agent) | Example plugin for framework-agnostic agentic rules. |
  527. | [`@alint-js/plugin-example-go`](https://github.com/moeru-ai/alint/tree/main/packages/plugin-example-go) | Example semantic Go review plugin using `plaintext`. |
  528. ## Documentation Automation
  529. The table of contents above is generated with `doctoc` so README navigation is not hand-written. Run this after changing headings:
  530. ```bash
  531. pnpm docs:update
  532. ```
  533. `docs:update` refreshes the root README TOC and then copies the root README to `packages/cli/README.md`, keeping the npm README for `@alint-js/cli` in sync with the project overview.
  534. ## Development
  535. This repository is a pnpm workspace.
  536. ```bash
  537. pnpm install
  538. pnpm -F @alint-js/cli build
  539. pnpm -F @alint-js/core exec vitest run
  540. ```
  541. Before sending changes, run:
  542. ```bash
  543. pnpm typecheck
  544. pnpm lint
  545. ```
  546. ## Status
  547. `alint` is early and APIs may change. The core direction is stable: lint-style diagnostics, model-backed rules, flat configs, provider setup, and optional agent adapters.
  548. ## License
  549. MIT
  550. [npmx-version-src]: https://npmx.dev/api/registry/badge/version/@alint-js/cli
  551. [npmx-version-href]: https://npmx.dev/@alint-js/cli
  552. [npmx-downloads-src]: https://npmx.dev/api/registry/badge/downloads-month/@alint-js/cli
  553. [npmx-downloads-href]: https://npmx.dev/@alint-js/cli
  554. [bundle-src]: https://npmx.dev/api/registry/badge/size/@alint-js/cli
  555. [bundle-href]: https://bundlephobia.com/result?p=@alint-js/cli
  556. [license-src]: https://npmx.dev/api/registry/badge/license/@alint-js/cli
  557. [license-href]: https://github.com/moeru-ai/alint/blob/main/LICENSE
  558. [jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
  559. [jsdocs-href]: https://www.jsdocs.io/package/@alint-js/cli

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.