Atlas works with Ruff through the CLI, because Ruff has no first-party MCP server and Astral's proposal is still open. Atlas drives the CLI with a JSON output format, reading rule codes and byte offsets rather than parsing human text. Have Atlas run ruff check --output-format=json . and set 'ruff check *' to allow while keeping 'ruff check --fix *' at ask under permission.bash.
Ruff has no first-party MCP server yet
Ruff has no first-party MCP server in 2026, and Astral's proposal for one is still open. So Atlas drives the Ruff CLI directly. That costs nothing in practice, because Ruff already emits structured diagnostics, and structured diagnostics are the only interface an agent needs from a linter.
It is worth knowing the state of play so you do not go searching for a package that has not shipped. Astral's MCP proposal for Ruff remains open, which means there is no first-party server to add with atlas mcp add. The CLI path is not a downgrade. Ruff's JSON output carries every rule code and every byte offset, which is more precise information than most linters expose. Atlas is terminal-native, so calling ruff check in the repo where pyproject.toml already configures it is the natural way for the agent to work anyway.
Structured diagnostics with --output-format=json
Have Atlas run ruff check --output-format=json . so it reads structured diagnostics carrying 2 things: rule codes and byte offsets. Byte offsets are the detail that matters, because they point Atlas at the exact span of the violation rather than the line, which makes the edit it proposes precise.
Ruff's JSON diagnostics are unusually good for an agent to consume. Each one carries the rule code, which names exactly which check fired, and the byte offsets, which delimit the exact region of source the check objected to. Atlas can therefore reason about the precise span rather than re-deriving it from a line number and a guess. Run ruff check --output-format=json . at the repo root and Ruff respects the configuration in pyproject.toml, so the rule set Atlas sees is the rule set your project actually enforces rather than Ruff's defaults.
The other output formats: sarif, github, junit, and more
Ruff supports 7 other output formats when you need them: json-lines, sarif, rdjson, github, gitlab, junit, and concise. Each targets a different consumer, so pick json for Atlas, sarif or github for code scanning surfaces, and junit when a CI system expects a test-report shape.
Knowing the full list saves you from bending one format into a job it was not meant for. The json-lines format streams one diagnostic per line, which suits a very large codebase where you would rather not build one giant document. The sarif and rdjson formats plug into code review and code scanning tooling. The github and gitlab formats produce annotations native to those platforms. The junit format lets a CI system that speaks test reports ingest lint results. The concise format is for humans in a hurry. For Atlas, ruff check --output-format=json . is the right default.
Formatting is a separate command: ruff format --check --diff
Formatting is a separate command in Ruff, so run ruff format --check --diff . to see exactly what would change. Those 2 flags work together: --check reports without writing, and --diff prints the proposed changes, so Atlas can inspect a reformat before a single file is touched.
Keep linting and formatting distinct in your head, because Ruff does. The ruff check command reports rule violations. The ruff format command reformats code. Combining --check and --diff gives you the safest possible preview: Ruff tells you what it would rewrite and shows the diff, without modifying anything on disk. That is exactly what you want an agent to run first. Atlas reads the diff, you agree it is only whitespace and layout, and only then does anyone let ruff format write. On a codebase that has never been Ruff-formatted, that preview can be large, which is precisely why you want to see it before it lands.
The --fix-only and --output-format json bug
Avoid combining --fix-only with --output-format json, which emits nothing because of a known Ruff bug. As of 2026, an agent that runs that combination sees an empty result and concludes there was nothing to fix, which is a silent failure and the worst kind for an automated loop.
The danger here is not that the command errors. It is that it succeeds and returns nothing, so Atlas has no signal that anything went wrong. It will reasonably report that the code is clean. Keep the two operations separate instead. Run ruff check --output-format=json . to read diagnostics as structured data, and run the fixing pass as its own invocation without asking for JSON from it. Splitting them also fits the permission model below, where reading and rewriting are deliberately given different levels of trust.
Permissions: allow 'ruff check *', ask on 'ruff check --fix *'
Set 'ruff check *' to allow and 'ruff check --fix *' to ask under permission.bash, so Atlas can read freely and only rewrite with approval. Those 2 rules split reading from writing: diagnostics are safe and constant, while rewriting source deserves a moment of human attention.
The asymmetry is the whole design. Running ruff check --output-format=json . does not modify a single file, so allowing it means Atlas can inspect the codebase as often as the task requires with no friction and no prompts. Adding --fix changes the picture entirely, because now Ruff is rewriting your source, so mapping 'ruff check --fix *' to ask puts that behind an approval you actually see. Two lines in permission.bash give you an agent that investigates freely and edits only with consent, which is the correct default for any linter that can autofix.
Setup
- 01Skip the MCP search: Ruff has no first-party MCP server (Astral's proposal is still open), so Atlas drives the CLI directly.
- 02Have Atlas run ruff check --output-format=json . so it reads structured diagnostics with rule codes and byte offsets.
- 03Reach for another format only when a tool needs it: json-lines, sarif, rdjson, github, gitlab, junit, and concise all exist.
- 04Preview reformats separately with ruff format --check --diff . which shows exactly what would change without writing.
- 05Avoid combining --fix-only with --output-format json, which emits nothing because of a known ruff bug.
- 06Set 'ruff check *' to allow and 'ruff check --fix *' to ask under permission.bash, so Atlas can read freely and only rewrite with approval.
Frequently asked questions
- is there a Ruff MCP server
- No. Ruff has no first-party MCP server and Astral's proposal is still open, so Atlas drives the Ruff CLI directly with a JSON output format.
- how do I get JSON output from Ruff for an AI agent
- Run ruff check --output-format=json . Atlas then reads structured diagnostics with rule codes and byte offsets instead of parsing human text.
- what output formats does ruff check support
- Beyond json, Ruff supports json-lines, sarif, rdjson, github, gitlab, junit, and concise. Use json for Atlas and the others for CI and code scanning tools.
- why does ruff --fix-only with json output return nothing
- It is a known ruff bug. Avoid combining --fix-only with --output-format json, because it emits nothing and an agent reads that as a clean codebase.
- how do I preview what ruff format would change
- Run ruff format --check --diff . Formatting is a separate command from ruff check, and those two flags report the proposed changes without writing them.
- how do I let an AI agent lint but not autofix
- Set 'ruff check *' to allow and 'ruff check --fix *' to ask under permission.bash. Atlas can then read diagnostics freely and only rewrite source with your approval.
- does Ruff lint and format with the same command
- No. Formatting is a separate command. Use ruff check --output-format=json . for diagnostics and ruff format --check --diff . to preview formatting changes.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Qwen2.5 7B Instruct in 2026: The Cheap Dense Small Model
Qwen2.5 7B Instruct runs Atlas's small_model slot at $0.175 per Mtok input and $0.70 per Mtok output, keeping the full 131,072 token window on a dense 7B checkpoint.
Atlas with Llama 3.1 405B: The 243GB Landmark in 2026
Llama 3.1 405B in Atlas for 2026: 405 billion openly released parameters, a 128,000 token window, Free (self-hosted), and a 243GB download that decides everything.
Atlas vs Base44: Terminal AI Coding Agents in 2026
Compare Atlas, the terminal-native AI coding agent, with Base44, the Wix-owned no-code app builder, for developers in 2026. Evaluate features, pricing, and workflow.
Diagnose a Hanging or Long-Running Command with Atlas in 2026
How to diagnose a hanging command with Atlas in 2026: the bash tool races every command against a timeout and tells you whether it is slow or blocked on input.
Atlas for Python in 2026
Atlas is a terminal-native AI coding agent for Python in 2026. Run it in a repo with a pyproject.toml or requirements.txt and review every diff before it lands.
Atlas with DeepSeek Coder 33B (Ollama): Local Setup and Tradeoffs in 2026
DeepSeek Coder 33B (Ollama) drives Atlas locally from 19GB of weights with a 16K token context and no API bill. Setup, VRAM budget, and honest tradeoffs for 2026.
Atlas with GPT-5.1 Codex Max: The Cheapest Codex Tier in 2026
GPT-5.1 Codex Max still bills at the November 2025 rate of $1.25 / $10 per Mtok on a 400K window. The lowest-cost entry into OpenAI's Codex post-training for Atlas.
Atlas vs Traycer in 2026: Terminal Agent That Writes Code vs a Planning Layer Above One
Atlas vs Traycer in 2026. Traycer plans and verifies but writes no code itself, so you pay it on top of an agent. Atlas plans and writes, free and open source.