arklint

The architectural rulebook for your codebase. Prevention, not detection.

Arklint enforces architectural rules before bad code ever lands - whether written by AI agents or humans. It's language-agnostic, runs locally with zero cloud dependency, and requires no external services.

This package is a thin Node.js wrapper. On first run it downloads the platform-specific prebuilt binary from GitHub Releases and caches it locally. No Python required.

Supported platforms: Linux x64, macOS ARM64 (Apple Silicon), Windows x64.

Installation

# Run once without installing
npx arklint check

# Install globally
npm install -g arklint

Quick start

# 1. Create a starter config in your project root
arklint init

# 2. Edit .arklint.yml to match your architecture

# 3. Check your codebase
arklint check

# 4. In CI - exit 1 on any violation
arklint check --strict

Key commands

| Command | Description | |---------|-------------| | arklint init | Create a starter .arklint.yml | | arklint check | Scan the codebase against all rules | | arklint check --strict | Exit 1 on warnings too | | arklint check --diff origin/main | Only scan changed files | | arklint check --json | Machine-readable JSON output | | arklint check --github-annotations | GitHub Actions inline PR annotations | | arklint validate | Validate config without running checks | | arklint search <query> | Search official rule packs | | arklint add arklint/fastapi | Add an official rule pack | | arklint visualize | Generate a Mermaid diagram of your rules | | arklint export --format cursorrules | Export rules for Cursor/Claude/Copilot | | arklint learn --provider anthropic | AI-powered rule generation | | arklint watch | Re-run checks on every file save | | arklint mcp | Start MCP server for AI agent integration |

Example .arklint.yml

version: "1"

# Extend an official rule pack
extends:
  - arklint/fastapi

# Add your own project-specific rules
rules:
  - id: no-direct-db-in-routes
    type: boundary
    description: "Routes must not import the database layer directly"
    source: "routes/**"
    blocked_imports:
      - "sqlalchemy"
      - "psycopg2"
    severity: error

  - id: layered-architecture
    type: layer-boundary
    description: "Enforce routes → services → repositories"
    layers:
      - name: routes
        path: "routes/**"
      - name: services
        path: "services/**"
      - name: repositories
        path: "repositories/**"
    allowed_dependencies:
      routes: [services]
      services: [repositories]
      repositories: []
    severity: error

Official rule packs

arklint search fastapi
arklint add arklint/fastapi
arklint add arklint/django
arklint add arklint/nextjs
arklint add arklint/express
arklint add arklint/clean-arch

Use in CI (Node.js projects)

# .github/workflows/arklint.yml
- name: Run arklint
  run: npx arklint check --diff origin/main --strict

Or if installed globally via npm:

- name: Install arklint
  run: npm install -g arklint

- name: Run arklint
  run: arklint check --diff origin/main --strict

MCP server (AI agents)

The MCP server is bundled — no extra install needed.

arklint mcp

Claude Code — add to .claude/settings.json:

{
  "mcpServers": {
    "arklint": {
      "command": "arklint",
      "args": ["mcp"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "arklint": {
      "command": "arklint",
      "args": ["mcp"]
    }
  }
}

Export rules for AI assistants

Keep your AI coding tools aligned with the same architectural constraints:

arklint export --format cursorrules   # → .cursorrules
arklint export --format claude        # → CLAUDE.md
arklint export --format copilot       # → .github/copilot-instructions.md

Full documentation

arklint.elevane.org · GitHub · PyPI · NuGet

License

MIT © Kaushik13k