The agent surface

alint treats a coding agent as a first-class consumer. Your one rule set drives two feeds: export-agents-md renders the rules into an AGENTS.md section the agent reads at the start of a session, and alint check --format agent emits each violation as machine-actionable JSON with an exact fix_command. The rules become both the agent’s standing instructions and its fix loop.

The agent output format

alint check --format agent emits one JSON envelope. It is a check-only format: alint fix accepts only human, json, or markdown, and rejects --format agent. The envelope has four top-level fields, stable behind schema_version:

• schema_version and a literal format: "agent".
• summary: total_violations, by_severity (error / warning / info), fixable_violations, passing_rules, failing_rules.
• violations: a single flat array (unlike --format json, which nests by rule).

Each violation object carries rule_id, severity, the location (file, line, column, present only when the finding has one), human_message (the rule’s message verbatim), an agent_instruction, fix_available, a fix_command when the finding is fixable, and a policy_url when the rule declares one. The agent_instruction starts from a templated remediation sentence, "<severity>: <message>. To resolve: edit <path>:<line>:<col>" (or a repository-level phrasing for a path-less finding); a fix hint is appended when the finding is fixable and a policy hint when a policy_url is set, and the whole always closes with a period. The fix_command is the argv after the alint program name, ["fix", "--only", "<rule-id>"], so an agent runs the fix without parsing English, and a CLI-parse test guarantees it only ever names flags the binary accepts.

export-agents-md

alint export-agents-md renders the active rule set into a directive block, grouped by severity, shaped for an agent-instruction file. By default it prints to stdout; --output <path> writes a file; and --inline (the canonical workflow, which requires --output) splices the block into that file between <!-- alint:start --> and <!-- alint:end --> markers, creating them if absent, so re-running keeps just that section in sync and leaves the rest of the file untouched. --section-title sets the heading, --include-info adds info-level rules (excluded by default), and --format json emits the machine shape instead of the default markdown. Because agents read these files at the start of a session, the same config that gates CI becomes the agent’s standing instructions.

Bundled agentic rulesets

Two bundled rulesets target the agentic era, adopted through extends: like any other:

• alint://bundled/agent-context@v1 lints the agent-instruction files themselves. It guards against stubs and bloat across all five it knows (AGENTS.md, CLAUDE.md, .cursorrules, GEMINI.md, .github/copilot-instructions.md), recommends a repo ship one of the first three, and flags stale backticked paths in AGENTS.md and CLAUDE.md.
• alint://bundled/agent-hygiene@v1 catches residue that is distinctly AI-shaped: versioned duplicate filenames, scratch-doc sprawl, AI-affirmation prose, debug residue, and model-attributed TODOs.

version: 1
extends:
  - alint://bundled/agent-context@v1
  - alint://bundled/agent-hygiene@v1

In practice

Run alint as an agent would, asking for the machine feed:

alint check --format agent

One fixable finding comes back as a flat object with a ready-to-run fix_command:

{
  "schema_version": 1,
  "format": "agent",
  "summary": {
    "total_violations": 1,
    "by_severity": { "error": 0, "warning": 1, "info": 0 },
    "fixable_violations": 1,
    "passing_rules": 12,
    "failing_rules": 1
  },
  "violations": [
    {
      "rule_id": "no-trailing-whitespace",
      "severity": "warning",
      "file": "src/app.rs",
      "line": 12,
      "column": 80,
      "human_message": "trailing whitespace",
      "agent_instruction": "warning: trailing whitespace. To resolve: edit src/app.rs:12:80 (or run `alint fix --only no-trailing-whitespace` to apply the auto-fix).",
      "fix_available": true,
      "fix_command": ["fix", "--only", "no-trailing-whitespace"]
    }
  ]
}

The agent runs fix_command and the loop closes without it ever reading human output. To keep the standing instructions current, splice them on every rules change:

alint export-agents-md --inline --output AGENTS.md

Going deeper

• Fixing is what a fix_command invokes under the hood.
• Configuration covers the output-format flag and extends: for the bundled rulesets.
• Rules lists the agent-context and agent-hygiene rulesets and their kinds.