Aider vs Claude Code: Fewer Surfaces, Fewer Locks

Aider vs Claude Code looks like a comparison of two terminal agents and behaves like a comparison of two philosophies about how much machinery an agent should carry. Measured on this site's own repository on 2026-08-13, 1 of 6 configuration surfaces survives a move from Claude Code to Aider — the worst score of any agent we have audited, and the only one where renaming your instruction file does not help. That number is a real cost, and for some workflows it is also the feature.

Key takeaways

• Aider auto-discovers no instruction file. Not CLAUDE.md, not AGENTS.md, not CONVENTIONS.md — a conventions file loads only when you name it explicitly.
• Aider's configuration reference documents no subagents, no skills, and no hooks. Those concepts do not translate; they disappear.
• Of six config surfaces on this repo, only project instructions survive the move, and only by being declared in .aider.conf.yml.
• Aider is open source and model-agnostic — you bring your own API key and can point it at a local model, which is the one structural freedom Claude Code does not offer, and it is worth exactly what its release cadence is worth.
• The explicit-context model is a deliberate design, not an omission. It is also why Aider is the least surprising of these tools to run on a repository you do not fully trust.

Aider vs Claude Code at a glance

We are deliberately not re-running the open-source roundup here. If you want Aider set against Continue and Cline rather than against Claude Code, that comparison is its own article and it answers a different question. This one is a head-to-head, and the head-to-head turns on scope. For the broader category decision, the best AI coding assistants comparison covers where each tool expects you to work.

What this article does not do: Aider is not installed on the machine this was written on, so there is no claim here about edit quality, speed, or how either tool handles a given task. Claude Code figures are first-hand and reproducible; Aider figures come from its published documentation, cited inline.

The measurement that decides it

The same audit that produced our three-way terminal agent comparison takes an Aider target.

npm run check:portability -- --agent=aider

  CONCERN                   CLAUDE CODE                 PRESENT     IN GIT   PORTS AS  AIDER
  Project instructions      CLAUDE.md                   8,189 B     yes      declare   read: in .aider.conf.yml
  Path-scoped instructions  .claude/rules/              absent               none      —
  MCP servers               .mcp.json                   284 B       yes      none      —
  Subagents                 .claude/agents/             2,443 B     yes      none      —
  Permissions / approvals   .claude/settings.local.json 4,263 B     no       none      --yes-always  (flag, not a list)
  Skills                    .claude/skills/             absent               none      —

  4 of 6 surfaces present. 10,916 B committed, 1 present but not in git — machine-local under either agent.
  Formats in play: markdown, JSON. Aider wants: YAML.

Project instructions

  CLAUDE.md            8,189 B
  Aider byte cap       no instruction file is auto-discovered.
  Claude Code cap      none. Loaded in full regardless of length.

  .aider.conf.yml      absent
  read: entry          none — Aider auto-discovers no instruction file
  Config home          .aider.conf.yml  (repo root or home)

  What Aider would read from this repo today: nothing.

Five none verdicts in one column. Against Codex CLI this repository produces four rewrite verdicts — work to do. Against Aider it produces five none verdicts, which is not work to do but capability that does not exist on the far side.

That distinction is the whole article. A rewrite is an afternoon. A none is a workflow change.

Aider discovers no instruction file

Every other agent we have measured reads something at session start. Claude Code walks up the tree concatenating CLAUDE.md. Codex CLI and Antigravity CLI both look for AGENTS.md. Aider looks for nothing, and this is documented behaviour rather than a gap.

Aider's conventions documentation is explicit that a conventions file has to be named:

# one file
read: CONVENTIONS.md

# or several
read: [CONVENTIONS.md, ARCHITECTURE.md]

The docs recommend /read CONVENTIONS.md or aider --read CONVENTIONS.md specifically because that path marks the file read-only and caches it when prompt caching is on. So the explicitness buys something concrete — the file is never accidentally edited by the agent, and it is never silently re-sent at full price.

One practical consequence: Aider's docs suggest keeping a conventions file to roughly 150–200 lines, because longer files start getting ignored in practice. This repository's instruction file is 8,189 bytes, well past that guidance, and it was written for a tool that loads it in full regardless of length. Moving it to Aider is an editing job, not a copy.

What Aider does not have

Stated plainly, because this is the part that decides the comparison for most people already using Claude Code seriously.

Aider's configuration reference documents four mechanisms: command-line switches, .aider.conf.yml, AIDER_-prefixed environment variables, and a .env file. It documents no subagents, no skills, and no hooks. Those are not renamed or restructured — there is no equivalent concept.

• Subagents. This repo commits two, at 2,443 bytes, and we wrote up how they behave in practice. Under Aider, that work is not portable and not replaceable.
• Skills. No equivalent.
• Hooks. No equivalent, so anything you automate around the agent's lifecycle becomes shell scripting around the agent instead.
• Permissions. Claude Code accumulates a per-call allowlist — 4,263 bytes of it here. Aider's closest equivalent is --yes-always, which is a switch rather than a list, so the granularity is gone in both directions.

If none of those four are in your workflow, this section costs you nothing. If two or more are, the comparison is effectively over and Aider is not the tool.

What Aider has that Claude Code does not

The trade runs the other way on three things, and they are not small.

You choose the model. Aider is model-agnostic and you supply the API key, so the same tool runs against a frontier model today and a local one tomorrow without changing your workflow. Claude Code is Anthropic's client for Anthropic's models. If model choice is a procurement requirement, a cost lever, or an air-gap requirement, this single row settles the decision.

That caveat cuts directly into the advantage above, and it should. Model-agnostic is only worth what the model list is worth: the freedom to point Aider at any provider does not help if the release that recognises this quarter's models has not shipped. We tracked the same pattern in the open-source roundup, and it is the reason that article ranks Cline ahead of Aider on maintenance signals while still preferring Aider's terminal-and-git shape.

Re-checked on 2026-08-14, that gap has widened rather than closed: Aider stood at 83 days since its last push against a field mostly measured in hours, which is the figure our 2026 terminal field survey opens with. Cline is the sharpest contrast and now runs in a terminal too, so it competes with Aider directly on this article's own ground — we take Cline against Claude Code apart on the same six surfaces.

You can read the source. Aider is open source, which means its defaults are auditable rather than documented. We have needed that twice on this site — including reading Codex CLI's byte cap out of its source because the published reference omitted the default — and it is a real advantage when a behaviour surprises you.

Git is the interface. Aider commits after each change by default, so the review surface is git diff and the undo is git reset. Claude Code edits the working tree and leaves committing to you. Neither is better in the abstract, but Aider's model degrades more gracefully when the agent is wrong: every step is already a commit you can drop.

That last point pairs badly with running both tools against the same working tree simultaneously, which is worth avoiding for exactly this reason.

The MCP question we could not settle

We could not confirm whether Aider ships a native MCP client, and rather than pick a side we are recording the state of the evidence.

Aider's own configuration reference documents no MCP support — no client, no server list, no transport settings. Third-party write-ups from 2026 contradict each other directly: some describe configuring MCP servers in Aider's YAML config, and at least one states flatly that Aider has no native MCP support and that configs claiming otherwise are fabricated.

What definitely exists is the reverse relationship. There are community MCP servers that wrap Aider so that other clients — Claude Code included — can delegate editing work to it. That is Aider as a tool being called, not Aider as a client calling tools, and it is an easy thing to misread when skimming a repository name.

So the portability audit records this surface as none, on the basis of the vendor's own documentation, and the honest caveat is that this is an absence of documentation rather than a documented absence. If you need MCP under Aider, verify it against the current release before committing to it — and if you are configuring MCP under Claude Code instead, our .mcp.json reference covers the schema and the path-resolution trap.

Which one to use

• Use Claude Code if you use subagents, skills, or hooks. They have no Aider equivalent, and this is a one-question decision.
• Use Aider if model choice is a requirement — but check the current release first. Procurement constraints, local models, and provider-level cost control are all things Claude Code structurally cannot give you, and all three depend on Aider shipping support for the model you want.
• Use Aider if you want every agent step to be a commit. The git-native workflow is a genuinely different safety model, not a stylistic preference.
• Use Claude Code if your configuration is a team asset. .claude/ and .mcp.json are built to be committed and read by everyone; .aider.conf.yml can be committed but carries far less.
• Do not choose on price without measuring your own volume. Bring-your-own-key and bundled subscription are different billing shapes, and what AI coding assistants actually cost covers why the sticker figure rarely decides it.

Common mistakes choosing between them

• Expecting your CLAUDE.md to load. It will not, under any filename. Add a read: entry or the agent works with no conventions at all and never says so.
• Porting a 200-line-plus instruction file unedited. Aider's own guidance is 150–200 lines before adherence degrades; Claude Code has no cap and encourages longer files.
• Reading "Aider MCP server" as MCP client support. Those community projects let other clients drive Aider, which is the opposite direction.
• Assuming open source means feature parity. Aider is open source and has roughly a sixth of the configuration surface. Those facts are unrelated.
• Running both against the same working tree at once. Aider's auto-commit will capture whatever Claude Code has half-written.

Conclusion

If subagents, skills, or hooks are in your workflow, this comparison is already decided and Aider is not a replacement — five of six configuration surfaces have no destination. If your requirement is model choice, an auditable open-source tool, or a git-native loop where every agent step is a droppable commit, Aider is the better tool and the missing machinery is largely machinery you were not going to use. Before you move either way, add a read: entry naming your conventions file, because that is the only failure here that produces no error and no output — just an agent that quietly disagrees with everything your team decided.

Frequently asked questions

Muhammad Kashif

Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.