auto-linter 1.8.0

MCP server for autonomous linting and architecture auditing

Auto Linter

Autonomous code quality for AI agents and developers.

AI Agent Integration

AI agents use the MCP interface to perform automated linting and code quality tasks:

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
Prototype Developer	Quick Start	Fast AI-assisted coding
Architecture Engineer	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

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
Rapid Iteration	Fast feedback loop, automated 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 (-5 points per violation, CRITICAL).

Dependency Rules

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

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.