AI Linter

AI-powered code linter using OpenAI Codex CLI with GitHub MCP integration for intelligent Pull Request reviews.

Features

- 🤖 AI-Powered Reviews: Uses OpenAI Codex CLI as an intelligent agent
- 📋 Configurable Rules: Customizable style guidelines (defaults to STYLE-GUIDELINES.md)
- 🔗 GitHub Integration: Native GitHub MCP support for posting PR comments
- 🌍 Global CLI: Install once, use anywhere
- 🚀 Context-Aware: Full repository access for better analysis
- ⚡ Non-blocking: Iterative review process without token context limits

Installation

$3

- Node.js 22+
- Go 1.24+ (for building GitHub MCP Server)

$3

``bash
npm install -g ai-linter-cli
`

After installation, you need to install OpenAI Codex globally:

`bash


Navigate to the global installation directory

cd $(npm root -g)/ai-linter-cli

Install OpenAI Codex globally

npm run install:codex
`

Finally, you need to build the Github MCP locally:

`bash


Navigate to the global installation directory

cd $(npm root -g)/ai-linter-cli

Build the MCP from source

npm run build:github-mcp
`

Usage

$3

`bash


Review a specific PR

ai-linter --repo-owner myorg --repo-name myrepo --pr 123

Review with custom style guidelines

ai-linter --repo-owner myorg --repo-name myrepo --pr 123 --rules ./docs/STYLE-GUIDE.md

Review with a specific model (default: gpt-5-codex)

ai-linter --repo-owner myorg --repo-name myrepo --pr 123 --model o1-preview

Dry run (show what would be reviewed)

ai-linter --repo-owner myorg --repo-name myrepo --pr 123 --dry-run

Verbose output

ai-linter --repo-owner myorg --repo-name myrepo --pr 123 --verbose
`

$3

AI Linter works best as a GitHub App that automatically reviews PRs. See the GitHub App Setup section below.

GitHub App Setup

$3

1. Go to your GitHub settings to create a new app:
- Personal account: https://github.com/settings/apps/new
- Organization: https://github.com/organizations/YOUR_ORG/settings/apps/new

2. Configure the app with these settings:
- Name: AI Linter
- Description: AI-powered code review and style guideline enforcement
- Homepage URL: Your repository URL
- Webhook: Uncheck "Active" (we use GitHub Actions)
- Permissions:
- Contents: Read
- Pull requests: Write
- Subscribe to events: Pull request

3. Click "Create GitHub App"

$3

1. After creation, scroll to "Private keys"
2. Click "Generate a private key"
3. Save the downloaded .pem file securely

$3

1. Click "Install App" in the sidebar
2. Choose repositories to install on
3. Click "Install"

$3

Add these secrets to your repository (Settings → Secrets → Actions):
- AI_LINTER_APP_ID: Your GitHub App's ID or Client ID (found on app settings page)
- AI_LINTER_PRIVATE_KEY: Contents of the .pem file
- AI_LINTER_OPENAI_KEY: Your OpenAI API key

$3

Create .github/workflows/ai-linter.yml:

`yaml
name: AI Linter

on:
pull_request:
types: [opened, synchronize, reopened]

permissions:
contents: read
pull-requests: write

concurrency:
group: pull_request-${{ github.head_ref }}
cancel-in-progress: true # Avoid running multiple workflows simultaneously to prevent deleting other reviews

jobs:
ai-lint:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'

- name: Install AI Linter
run: npm install -g ai-linter-cli

- name: Build GitHub MCP Server
run: |
cd $(npm root -g)/ai-linter-cli
npm run build:github-mcp

- name: Install Codex
run: |
cd $(npm root -g)/ai-linter-cli
npm run install:codex

- name: Generate GitHub App Token
id: generate_token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.AI_LINTER_APP_ID }}
private-key: ${{ secrets.AI_LINTER_PRIVATE_KEY }}

- name: Run AI Linter
env:
GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
AI_LINTER_OPENAI_KEY: ${{ secrets.AI_LINTER_OPENAI_KEY }}
working-directory: ${{ github.workspace }}
run: |
ai-linter \
--repo-owner ${{ github.repository_owner }} \
--repo-name ${{ github.event.repository.name }} \
--pr ${{ github.event.pull_request.number }} \
--base=${{ github.base_ref }} \
--head=${{ github.head_ref }}
`

Style Guidelines

AI Linter looks for a STYLE-GUIDELINES.md file in your repository. If not found, it will create a default one.

Common locations checked:
- ./STYLE-GUIDELINES.md
- ./docs/STYLE-GUIDELINES.md
- ./.github/STYLE-GUIDELINES.md

Configuration

$3

- AI_LINTER_OPENAI_KEY: Required - Your OpenAI API key
- GITHUB_TOKEN: GitHub App installation token (provided by GitHub Actions)
- GITHUB_PERSONAL_ACCESS_TOKEN: Alternative to GitHub App token for local development

$3

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| --rules | -r | Path to style guidelines file | STYLE-GUIDELINES.md |
| --pr | -p | Pull Request number to review | - |
| --base | -b | Base branch for comparison | main |
| --head | -h | Head branch for comparison | Current branch |
| --model | -m | OpenAI model to use | gpt-5-codex |
| --repo-owner | -o | GitHub repository owner | Auto-detected |
| --repo-name | -n | GitHub repository name | Auto-detected |
| --dry-run | - | Show what would be done without executing | false |
| --verbose | -v | Verbose logging | false` |

License

MIT