agentlint

Stateless, deterministic CLI that bridges traditional linters and AI-assisted code review.

agentlint uses tree-sitter to parse code, runs visitor-based rules that flag suspicious patterns, and outputs structured reports with natural language instructions. The output is designed to be consumed by an AI coding agent (Claude Code, Cursor, etc.) that evaluates each finding in context.

How it works

Phase 1 - Deterministic (agentlint)
  tree-sitter AST parsing -> visitor dispatch -> pattern match -> collect flags

Phase 2 - AI-evaluated (the calling agent)
  reads agentlint stdout -> evaluates each match per instructions -> acts

agentlint owns Phase 1 only. It does not call any AI model. It does not require an API key.

Quick start

pnpm add @aurelienbbn/agentlint

Create agentlint.config.ts:

import { defineConfig, defineRule } from "@aurelienbbn/agentlint";

const noNoiseComments = defineRule({
  meta: {
    name: "no-noise-comments",
    description: "Flags comments for AI evaluation",
    languages: ["ts", "tsx"],
    instruction: `Evaluate each comment. Is it noise or valuable?
Remove noise comments. Keep valuable ones.`,
  },
  createOnce(context) {
    return {
      comment(node) {
        const text = node.text.replace(/^\/\/\s*/, "").trim();
        if (text === "") return;
        context.flag({ node, message: `Comment: "${text.slice(0, 60)}"` });
      },
    };
  },
});

export default defineConfig({
  rules: { "no-noise-comments": noNoiseComments },
});

Run:

# Scan files changed in current branch
pnpm agentlint check

# Scan all files
pnpm agentlint check --all

# Scan specific files or globs
pnpm agentlint check src/utils.ts "src/**/*.tsx"

# List registered rules
pnpm agentlint list

# Mark flags as reviewed
pnpm agentlint review <hash...>

Output format

agentlint v0.1.0 - 1 rule(s) triggered, 3 match(es)

━━━ no-noise-comments: Flags comments for AI evaluation (3 match(es)) ━━━

  [abc1234] src/utils.ts:5:1  // Increment the counter
  [def5678] src/utils.ts:12:1  // Helper function
  [ghi9012] src/utils.ts:18:3  // TODO: implement later

  ┌─ Instruction ─────────────────────────────────────────
  │ Evaluate each comment. Is it noise or valuable?
  │ Remove noise comments. Keep valuable ones.
  └───────────────────────────────────────────────────────

3 match(es) across 1 rule(s)

CLI reference

agentlint check [files...] [options]

| Flag | Description | | --------------------- | --------------------------------------- | | --all, -a | Scan all files (not just git diff) | | --rule, -r <name> | Run only this rule | | --dry-run, -d | Show counts only, no instruction blocks | | --base <ref> | Git ref to diff against |

agentlint list

Lists all registered rules with their metadata.

agentlint init

Scaffolds a starter agentlint.config.ts file in the current directory.

agentlint review [hashes...] [options]

Manages per-developer reviewed-flag state. When you run agentlint check, flags that have been marked as reviewed are automatically filtered out of the output.

| Flag | Description | | ------------- | ---------------------------------------- | | --all, -a | Mark all current flags as reviewed | | --reset | Wipe the state file (.agentlint-state) |

Review workflow:

1. Run agentlint check to see current flags.
2. After evaluating a flag, mark it as reviewed by passing its hash:

   pnpm agentlint review abc1234 def5678

3. To mark every current flag as reviewed at once:

   pnpm agentlint review --all

4. Reviewed flags are stored in .agentlint-state (a local file, not committed to git). Future check runs hide them automatically.
5. To start fresh and see all flags again:

   pnpm agentlint review --reset

Contributing

See CONTRIBUTING.md for local development setup and how to write rules.

Security

Please report vulnerabilities privately as described in SECURITY.md.

License

MIT