auto-linter 1.7.0

MCP server for autonomous linting and architecture auditing

Auto Linter

Autonomous code quality. Built for AI agents that code 24/7.

🤖 AI Agent Benefits

In AI Era, no one manually codes anymore. Your AI agent does the work.

Benefit	Description
Autonomous Linting	Agent runs lint check without human intervention
Self-Healing Code	Agent auto-fixes issues automatically
Multi-Agent Collab	24/7 multi agents can coordinate via shared job registry
Continuous Quality	Agent enforces quality gates 24/7
Context-Aware	Agent understands architectural rules

Choose Your Path

I'm a...	Start Here	What I'll Do
AI Agent	SKILL.md	Autonomous linting, self-healing
Vibe Coder	Quick Start	Fast AI-assisted coding
Vibe Architect	Architecture	Architectural rules
Developer	Setup for AI Agents	Add features, fix bugs
Adapter Contributor	Contributing: Add Adapter	Integrate new linter tools
CLI Contributor	Contributing: Add CLI	Add new CLI commands

---

Why Use Auto Linter

Stop Wasting Hours on Manual Linting — Your competitors are already using automated quality gates.

For Users

Benefit	Description
Easy Config	Works out-of-the-box with sensible defaults
Multi-Language	Python, JavaScript, TypeScript in one tool
AI Ready	MCP server for automated code review
Vibe Mode	Fast AI-assisted iterations, quality gates
Architecture	Architectural rule enforcement (AES, Clean, Hexagonal, DDD)
CI-Ready	SARIF, JUnit, JSON reports with exit codes
Auto-Fix	Safe fixes applied automatically
Quality Trends	Track code quality over time

For Contributors

Benefit	Description
Well-Structured	6-domain architecture with clear boundaries
Comprehensive Tests	1518 tests (100% branch coverage)
Architecture Built-In	Linting architecture adapter prevents violations
Clear Paths	Documented guides for adapters, CLI, MCP
Active Project	Regular updates, responsive maintainer

Install

pip install auto-linter

Or with uv:

uv tool install auto-linter

Or zero-install:

uvx auto-lint check ./src/

Or one-liner installer (Linux/macOS):

curl -sSL https://raw.githubusercontent.com/rakaarwaky/auto-linter/main/install.sh | bash

Or for Windows (PowerShell):

Invoke-WebRequest -Uri https://raw.githubusercontent.com/rakaarwaky/auto-linter/main/install.ps1 | Invoke-Expression

Verify

auto-lint version auto-lint setup doctor

---

## Quick Start

```bash
# Lint your code
auto-lint check ./src/

# Auto-fix safe issues
auto-lint fix ./src/

# Security scan
auto-lint security ./src/

# Generate report
auto-lint report ./src/ --output-format json

---

Setup for AI Agents

Hermes Agent

pip install auto-linter
auto-lint setup hermes

This auto-detects DesktopCommander and configures Hermes automatically.

Claude Desktop / VS Code

auto-lint setup mcp-config --client claude

Copy the output to your MCP config file.

MCP Tools (5 tools)

The server registers 5 MCP tools:

Tool	Description
execute_command	Execute any CLI command
list_commands	List all available CLI commands with descriptions
read_skill_context	Read SKILL.md documentation sections
check_status	Check status of running lint jobs
health_check	Check DesktopCommander and transport health

Note: Job cancellation is a CLI command: auto-lint cancel <job_id>

---

Transport

Auto-linter connects to DesktopCommander for command execution. Supports 3 transport modes with auto-detection:

DESKTOP_COMMANDER_URL              Mode             Requires
──────────────────────────────────────────────────────────────
/run/desktop-commander/socket      Unix Socket      DesktopCommander
http://host:port/execute           HTTP             DesktopCommander HTTP wrapper
auto (default)                     Auto-detect      tries socket -> http -> stdio

The default socket path is /run/desktop-commander/socket. Set DESKTOP_COMMANDER_URL to override.

---

CLI Commands

Core

Command	Description
check <path>	Run all linters, check architecture score
	--git-diff flag: only lint changed files
scan <path>	Alias for check (CI-friendly)
fix <path>	Apply safe fixes automatically
report <path>	Generate quality report (text/json/sarif/junit)
ci <path>	CI-optimized with exit codes

Scans

Command	Description
security <path>	Bandit vulnerability scanning
complexity <path>	Cyclomatic complexity analysis
duplicates <path>	Code duplication detection
trends <path>	Quality trends over time
dependencies <path>	Dependency vulnerability scan

Setup

Command	Description
setup init	Auto-configure for your system
setup hermes	Auto-install into Hermes Agent
setup doctor	Diagnose configuration issues
setup mcp-config	Print MCP config for Claude/Hermes/VS Code

Dev

Command	Description
diff <path1> <path2>	Compare lint results between two versions
suggest <path>	AI-powered fix suggestions (--ai flag)
config show|edit|reset	View, edit, or reset configuration settings
export sarif|junit|json	Export lint reports to file (-o output)
import <config.json>	Import configurations from file
ignore <rule>	Manage ignore rules (--remove to delete)
init	Initialize a new Auto-Linter configuration
install-hook	Install git pre-commit hook
uninstall-hook	Remove git pre-commit hook

Maintenance

Command	Description
cancel <job_id>	Cancel a running job
stats <path>	Statistics dashboard
clean	Cleanup cache
update	Update adapters
doctor	Diagnose issues
version	Show version
adapters	List enabled linters

Other

Command	Description
watch <path>	Watch files and auto-lint on changes
batch <path1> <path2>	Check multiple paths
plugins	List discovered plugins
multi-project <paths...>	Lint multiple projects, aggregate

Full list: auto-lint --help

---

Configuration

.env (optional)

# DesktopCommander transport (auto-detected if not set):
DESKTOP_COMMANDER_URL=/run/desktop-commander/socket

# For JS/TS linters:
PHANTOM_ROOT=$HOME/

Create with: auto-lint setup init

auto_linter.config.python.yaml

thresholds:
  score: 100.0
  complexity: 10

output_dir: "output"

adapters:
  - name: "ruff"
    weight: 1.0
  - name: "mypy"
    weight: 1.0
  - name: "bandit"
    weight: 1.0
  - name: "radon"
    weight: 1.0
  - name: "architecture"
    weight: 3.0

---

Architecture

6-domain structure with strict architectural enforcement (AES):

src/
├── agent/              # Orchestration & DI. MANDATORY: contract(io)
├── capabilities/       # Thinking logic (pure). MANDATORY: contract(protocol)
├── contract/           # Definitions: _io (Agent), _port (Infra), _protocol (Cap)
├── infrastructure/     # Technical details (IO). MANDATORY: contract(port)
├── surfaces/           # Entry points (CLI, MCP). No logic allowed.
└── taxonomy/           # Shared language (Value Objects, Entities, Events)

Architectural Enforcement Standards (AES)

Auto Linter enforces a 100/100 compliance score based on these rules:

1. 3-Word Naming: Every file (except __init__.py) must have exactly 3 words separated by underscores (e.g., user_data_vo.py).
2. Mandatory Classes: Every logic file must encapsulate its logic in a class. Standalone functions are prohibited.
3. Contract Inheritance: Every class must inherit from a domain contract defined in src/contract/.
4. Strict Layering: No layer bypasses. Surfaces can only call the Agent layer. Infrastructure and Capabilities must be pure adapters/processors.
5. No Bypasses: Usage of # noqa, # type: ignore, or # nosec results in immediate failure (-50 points per violation).

Dependency Rules

agent          → taxonomy, contract, infrastructure, capabilities  ALLOWED
surfaces       → agent, taxonomy, contract(io)                     ALLOWED
surfaces       → infrastructure, capabilities                      FORBIDDEN
capabilities   → taxonomy, contract(protocol)                      ALLOWED
capabilities   → infrastructure, surfaces, agent                   FORBIDDEN
infrastructure → taxonomy, contract(port)                          ALLOWED
infrastructure → capabilities, surfaces, agent                     FORBIDDEN
contract       → taxonomy                                          ALLOWED
contract       → agent, capabilities, infrastructure, surfaces     FORBIDDEN
taxonomy       → taxonomy                                          ALLOWED
taxonomy       → agent, capabilities, infrastructure, surfaces, contract FORBIDDEN

Contract Governance

To prevent architectural bypasses, each layer must inherit from its corresponding contract type:

Layer	Suffix Rule	Mandatory Contract	Purpose
Agent	Strict	_io.py	Executive orchestration recipes
Capabilities	Flexible	_protocol.py	Pure domain logic interfaces
Infrastructure	Flexible	_port.py	Technical adapter abstractions
Surfaces	Strict	N/A	Entry points calling the Agent brain
Taxonomy	Strict	_vo.py etc.	Value Objects for domain integrity

[!IMPORTANT] Merely importing the contract is not enough. You MUST use the contract as a base class. The linter checks for semantic implementation via AST analysis.

---

Contributing

How to Add an Adapter

1. Create adapter in src/infrastructure/python_<tool>_adapter.py (3 words) implementing ILinterAdapterPort.
2. Register in src/agent/dependency_injection_container.py.
3. Add tests in tests/infrastructure/test_python_<tool>_adapter.py.
4. Run: auto-lint check src/ to verify 100.0 score.

See CONTRIBUTING.md for full details.

How to Add a CLI Command

1. Choose module in src/surfaces/cli_<domain>_command.py based on command type.
2. Add command using Click decorators within a handler class.
3. Register in src/surfaces/mcp_command_store.py.
4. Add tests.

See CONTRIBUTING.md for full details.

---

License

MIT License. See LICENSE.