0.3.8

ai-lint

A linter for your AI coding sessions.

ai-lint checks how you use AI — not the code it writes. Define your rules, and ai-lint reads your Claude Code sessions, evaluates them, and tells you what passed and what didn't.

No API keys. No dashboards. Runs locally.

---

It catches this

ai-lint flagged a session where an API key was exposed in the conversation.

---

And gives you this

Every session gets a clear verdict — what passed, what failed, and why.

---

Why

You lint your code. You lint your commits. But nobody lints how they work with AI.

• Are you leaking credentials in prompts?
• Are you blindly accepting AI output without reviewing?
• Are you stuck in error → paste → fix loops?
• Are your team members following the AI usage guidelines you wrote?

ai-lint answers these questions automatically.

---

Install

pip install ai-lint

Requires: Python 3.10+ and Claude Code CLI installed.

---

30-Second Setup

ai-lint init

This asks you one question — pick a persona:

• self — 10 rules for individual developers
• team — 11 rules for teams with AI usage policies

Creates your policy at ~/.ai-lint/policy.md.

If you don't like the default policies... you can edit them anytime.

---

Usage

Check your last session:

ai-lint check --last

Output:

[+] PASS  No credential exposure
[+] PASS  No sensitive data in prompts
[x] FAIL  Review before acceptance — Developer accepted output without review
[-] SKIP  Testing discussed or performed

8/10 passed

Check interactively (pick a session):

ai-lint check

Batch report (last 5 sessions → markdown):

ai-lint report -n 5

Auto-check after every session:

ai-lint hook install

Edit your policy:

ai-lint policy

---

What It Checks

Security

Developer Engagement

Process Discipline

---

Who It's For

Individual developers — Check your own AI habits. Get better at working with AI. Catch credential leaks before they become incidents.

Engineering managers — You wrote an AI usage policy. Now what? Give your team ai-lint. Each developer installs it, runs it locally, and self-checks against your policy. No surveillance dashboards, no monitoring infrastructure — just a shared policy.md that everyone checks against. Drop your AI usage guidelines into the policy file and your team has a compliance tool in 30 seconds.

Anyone with a policy — Edit ~/.ai-lint/policy.md with any rules you want, in plain English. ai-lint evaluates against whatever you write.

---

Custom Policies

The templates are starting points. Write your own rules:

ai-lint policy

# My AI Policy

1. Never use AI for authentication or payment code without explicit approval
2. Always run the test suite before ending a session
3. Reference a JIRA ticket in every session
4. Don't generate client-facing emails without human review
5. Keep sessions under 30 minutes

ai-lint sends your rules + the session transcript to Claude and gets back verdicts. Plain English rules just work.

---

How It Works

~/.claude/projects/*.jsonl    →    ai-lint    →    verdicts
   (session transcripts)        + policy.md      (PASS/FAIL/SKIP)

1. Reads Claude Code session transcripts (JSONL files stored locally)
2. Pairs them with your policy (~/.ai-lint/policy.md)
3. Sends both to claude -p (Claude Code CLI) — no API keys, runs locally
4. Returns structured verdicts with reasoning

---

Commands

---

Uninstall

ai-lint hook uninstall
rm -rf ~/.ai-lint
pip uninstall ai-lint

---

Contributing

There's a wide range of ways to contribute — from small additions to major features:

• New flags — --format json, --since date filter, --severity threshold, custom --policy path
• Report formats — PDF export, HTML reports, SARIF for IDE integration, JUnit XML for CI/CD
• New session sources — Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Windsurf, OpenCode, Entire CLI
• LLM providers — OpenAI, Gemini, Ollama (fully offline), any OpenAI-compatible endpoint
• Policy templates — industry-specific rules, new personas, community-contributed policies
• Bug fixes, docs, better output formatting

Every new session source just needs a parser that returns the same Session format — the checker doesn't care where the transcript came from.

License

MIT