# Deep-Dive DD-02 — Aider: The Git-Native Pair Programmer

**Course**: Master Course — Harness Engineering
**Deep-Dive**: DD-02
**Duration**: 60 minutes
**Level**: Senior Engineer and above
**Prerequisites**: Modules 0–12, DD-01 (Pi — the thin reference; Aider is the thin-medium reference this deep-dive compares against)

> *3 years of iteration. Git-first philosophy. Created the Aider Polyglot Benchmark — the field's de facto coding-agent benchmark. The thin-medium reference. The first harness to the right of Pi on the thickness spectrum, and the comparison question for the whole deep-dive is: how much thickness does git buy, and why?*

---

## The load-bearing claim

**Aider's git-first philosophy is the differentiator.** Pi (DD-01) has no memory, no checkpointing, no verification. Aider gets all three — plus permission and observability — *for free* by using git as the substrate for everything. One infrastructure choice (git) yields five rubric modules' worth of capability. This is why Aider scores +7 over Pi (32/60 vs 25/60), and the entire +7 comes from the git multiplier. No other harness in the deep-dive roster gets this much from a single decision. If you understand Aider, you understand the highest-leverage infrastructure choice a coding harness can make.

---

## Learning objectives

After this deep-dive, you will be able to:

1. Apply the 6-phase methodology (Module 0.3) to Aider and produce a scored card with file:line evidence.
2. **Explain Aider's git-first philosophy as a distinct architectural bet** — git-as-substrate yielding state, memory, verification, permission, and observability from one choice.
3. Compare Aider (thin-medium) against Pi (thin) module-by-module: what does the medium thickness buy, and what does it cost?
4. State why Aider's benchmark creation (the Aider Polyglot Benchmark) makes it the field's reference for coding-agent performance.
5. Articulate the critical limitation of git-gating: it catches *wrong* changes, not *malicious* ones — and why this matters for security.
6. Identify the three changes that would move Aider from "mature coding agent" to "production-grade coding agent" without compromising its git-first value.

---

## The subject

**Aider** is the benchmark creator. The numbers:

| Metric | Value |
| --- | --- |
| Language | Python |
| Stars | 44,500+ |
| License | Apache 2.0 |
| Model flexibility | 100+ via LiteLLM |
| Tools | ~8 |
| System prompt | ~2,000 tokens |
| Permission model | Git-gated |
| Total LOC | ~25,000 |

Aider invented the **Aider Polyglot Benchmark** — the de facto standard for evaluating coding agents across languages. Three years of iteration (2023–2026) have made it the most mature coding agent in the thin-medium range. It is the first harness to the right of Pi on the thickness spectrum, and every subsequent coding-focused harness in the roster is measured against Aider's git-first approach.

---

## Phase 1 — First Contact

Aider is Python — significantly larger than Pi (~25k LOC vs ~1.2k) but still readable. The entry point is `aider/main.py`. The git-first philosophy is visible immediately: Aider treats git as the substrate for everything — checkpoints, rollback, diff-based editing, and the permission model.

The system prompt (~2k tokens) is larger than Pi's (<1k) but still thin — it specifies the editing format (search/replace blocks), git conventions, and behavioral guidelines. The prompt grew because Aider has more to specify (the diff format, the repo-map, the git workflow), not because of over-engineering.

Aider's codebase rewards reading. The three years of iteration show: the diff-editing logic is battle-tested, the repo-map is tuned, and the git integration is deep (not a wrapper — Aider commits, resets, and branches as core operations).

---

## Phase 2 — Architecture Map

**Loop**: ReAct-derived, but specialized for code editing. Instead of generic tool-use, Aider uses a **diff-based editing format** — the model outputs search/replace blocks that Aider applies to files. This is more reliable than "write the whole file" (Pi's `write_file` approach) because it targets specific changes, costs fewer tokens, and avoids the hallucinated-full-file failure mode.

**Tools** (~8): `read_file`, `write_file`, edit (search/replace blocks), `bash`, search, plus git-specific operations (`git_add`, `git_commit`, `git_diff`). More than Pi's 4, but each is purpose-built for the coding use case. The extra tools add capability (git operations, structured editing) rather than decision noise.

**Permission model**: **Git-gated**. Aider commits after each change; the user can review the git diff and `git reset` if the change is wrong. This is a distinct permission architecture — not per-action approval (Module 6), but per-commit review with native rollback. It trades real-time approval for post-hoc review with version control.

**Context manager**: the **repo-map** — an AST-based file index that gives the model the repository structure without reading every file. This is Aider's context-management advantage over Pi (which has none): the model knows what files exist and what symbols they export, enabling targeted reads instead of blind exploration.

**Stop conditions**: `end_turn`, `max-iterations`. Plus: the user can interrupt at any time (Ctrl+C). No token budget, no error threshold. Similar to Pi here.

---

## Phase 3 — Design Decision Audit (12 modules)

| Module | Pattern | Tradeoff accepted | vs Pi |
| --- | --- | --- | --- |
| 1 Loop | ReAct + diff-based editing | specialized; less general | = (reliable for code) |
| 2 Tools | ~8, git-integrated | more than Pi; purpose-built | -1 (more noise, but purposeful) |
| 3 Context | repo-map (AST-based file index) | better than Pi's nothing | **+2** |
| 4 Memory | git as checkpoint | version-controlled state | **+2** |
| 5 Sandbox | none (OS process) | blast radius = host | = |
| 6 Permission | git-gated (post-hoc review + rollback) | not real-time | **+1** |
| 7 Errors | model self-corrects via diff failures | relies on model | +1 |
| 8 State | git commits | native rollback | **+3** |
| 9 Verification | the diff IS the verification (human reviews) | implicit verification | **+2** |
| 10 Subagents | none | — | = |
| 11 Observability | git log as the trace | human-readable history | **+1** |
| 12 Prompt | ~2k (editing format + git conventions) | more than Pi, still thin | -1 (less thin, more capable) |

**The git-first philosophy is the differentiator.** Pi has no memory, no checkpointing, no verification. Aider gets all three — for free — by using git as the substrate. This is the architectural insight that makes Aider the thin-medium reference: git gives you state (Module 8), memory across sessions (Module 4), verification (Module 9 — the human reviews the diff), permission (Module 6 — git-gated review), and observability (Module 11 — git log) — all from one infrastructure choice.

**Three decisions I agree with:**
1. **Git-as-substrate** — the multiplier. Five modules from one choice. No other decision in the roster delivers this much.
2. **Diff-based editing** — search/replace blocks are more reliable than whole-file writes. Three years of iteration refined this to the field's best.
3. **The repo-map** — AST-based context management that gives the model structure without bloating context. A clean middle path between Pi's nothing and a thick harness's full retrieval.

**Three decisions I would make differently:**
1. **Add a sandbox (Docker)** — blast radius is the host, same as Pi. Git-gating catches wrong changes but not malicious exfiltration.
2. **Add untrusted-content tagging on file reads** — a README read by the agent could contain injection that survives the diff-review.
3. **Add a token budget** — three years of iteration hasn't added one; a long session can still run away.

---

## Phase 4 — Security Audit

Same blast-radius issue as Pi: `bash` is full shell; no sandbox; no filesystem scope. **Git-gating means changes are reviewable, but a compromised Aider process can still read `~/.ssh` and exfiltrate before the human reviews the diff.** The git review catches wrong changes, not malicious ones — if the model is prompt-injected, it can commit a change that *looks* benign but includes an exfiltration payload (e.g., a "refactor" that also reads a credential file and curls it to an attacker URL).

This is the critical security nuance: **git-gating is a change-quality control, not an injection defense.** The diff-review answers "is this the change I asked for?" not "is this change safe to apply?" A prompt-injected model produces a change that is *exactly* what the attacker asked for, which may pass human review if the injection is subtle. This maps to OWASP ASI01 (Goal Hijacking via indirect injection) and ASI07 (Insecure Output Handling — the "output" is the diff, consumed by the human reviewer who may not spot the embedded payload).

---

## Phase 5 — Benchmark & Performance

Aider's defining contribution: the **Aider Polyglot Benchmark**. A standardized set of coding tasks across multiple languages, used by the field to evaluate coding-agent performance. Most published coding-agent benchmark numbers you see trace back to Aider's benchmark methodology. This is why Aider is the reference — not because it's the best harness, but because it *defined how the field measures "best."*

- **Token profile**: moderate. The ~2k prompt is larger than Pi's <1k, and the repo-map adds context, but the diff-based editing keeps per-edit token cost low (search/replace blocks vs whole files).
- **Maturity**: three years of iteration. The diff-editing, the repo-map, and the git integration are battle-tested in a way no newer harness matches.

---

## Phase 6 — Score & Synthesize

### Scoring sheet

| Module | Score (1–5) | Key decision | vs Pi |
| --- | --- | --- | --- |
| 1 Loop | 4 | ReAct + diff editing | = |
| 2 Tools | 4 | ~8, git-integrated | -1 |
| 3 Context | 4 | repo-map (AST index) | +2 |
| 4 Memory | 3 | git as checkpoint | +2 |
| 5 Sandbox | 1 | none | = |
| 6 Permission | 3 | git-gated | +1 |
| 7 Errors | 3 | diff-failure self-correct | +1 |
| 8 State | 4 | git commits | +3 |
| 9 Verification | 3 | diff-as-implicit-verification | +2 |
| 10 Subagents | — | n/a | = |
| 11 Observability | 3 | git log as trace | +1 |
| 12 Prompt | 4 | ~2k, editing format | -1 |
| **TOTAL** | **32/60** | | **+7 vs Pi** |

The +7 over Pi comes almost entirely from the git-first philosophy: +2 context (repo-map), +2 memory (git), +3 state (git), +2 verification (diff review), +1 permission (git-gated), partially offset by slightly more tool noise and prompt density. **Git is the multiplier.**

### Architect's Verdict (3 sentences)

> *Aider optimizes for coding reliability via git-as-substrate — using version control to get state, memory, verification, and permission from one infrastructure choice. It sacrifices generality (diff-based editing is coding-specific) and blast-radius safety (no sandbox, same as Pi). Build on Aider for any code-editing task where git is available; it is the field's most mature coding agent and the creator of the benchmark everyone else measures against.*

### MLSecOps Relevance (1 sentence)

> *Aider's git-gating provides change review and rollback but NOT injection defense — a prompt-injected model can commit a benign-looking change that contains an exfiltration payload, passing human diff-review while executing maliciously.*

### Three things Aider does better than any other studied harness

1. **Git-as-substrate**: state + memory + verification + permission + observability from one infrastructure choice. No other harness gets this much from a single decision.
2. **Benchmark creation**: defined how the field measures coding-agent performance. Every benchmark number traces to Aider's methodology.
3. **Diff-based editing reliability**: search/replace blocks are more reliable than whole-file writes. Three years of iteration have refined this to the field's best.

### Three things I would fix if I forked Aider

1. Add a sandbox (Docker) — the blast radius is the host, same as Pi.
2. Add untrusted-content tagging on file reads — a README read by the agent could contain injection.
3. Add a token budget — three years of iteration hasn't added one; a long session can still run away.

---

## Anti-patterns

### "Aider has git-gating, so it's secure"
Git-gating catches wrong changes, not malicious ones. A prompt-injected model produces a change that is exactly what the attacker asked for, which may pass human diff-review. Cure: treat git-gating as a change-quality control, not an injection defense. Add untrusted-content tagging if the agent reads attacker-controllable files.

### "Aider's diff-editing makes it general-purpose"
The diff-based editing format is coding-specific. Aider is optimized for code-editing tasks where search/replace blocks and git commits make sense. Cure: do not deploy Aider for non-coding tasks. Use Pi (or a Pi-derivative) for general tool-use; use Aider for code.

### "The repo-map is just context padding"
The repo-map is AST-based structure, not padding. It gives the model the repository's symbol graph without reading every file, enabling targeted reads. Cure: treat the repo-map as Module 3 context management — the model knows what exists and where, reducing blind exploration and the context-rot that comes with it.

### "Aider's ~8 tools violate the 4-tool philosophy"
The 4-tool philosophy (Pi) is a noise-reduction strategy for general tool-use. Aider's ~8 tools are all coding/git-specific and purpose-built — they add capability (git operations, structured editing) without the dispatch noise a general 5th tool would add. Cure: evaluate tool count against use case. Pi's 4 is correct for general; Aider's ~8 is correct for coding.

---

## Key terms

| Term | Definition |
| --- | --- |
| **Git-as-substrate** | Aider's architectural bet: git yields state, memory, verification, permission, and observability from one infrastructure choice. The +7 multiplier over Pi. |
| **Git-gated permission** | Post-hoc review + rollback via git. Catches wrong changes, not malicious ones. Distinct from real-time per-action approval (Module 6). |
| **Diff-based editing** | The model outputs search/replace blocks Aider applies to files. More reliable than whole-file writes; less token cost; avoids hallucinated-full-file errors. |
| **Repo-map** | An AST-based file index giving the model repository structure without reading every file. Aider's Module 3 context management. |
| **The git multiplier** | The +7 scoring advantage over Pi, almost entirely attributable to git yielding 5 modules' worth of capability. |
| **Benchmark creator** | Aider created the Aider Polyglot Benchmark — the field's de facto coding-agent evaluation. |

---

## Lab exercise

See `07-lab-spec.md`. You model Aider's git-gated loop as a trace, score Aider against Pi module-by-module to confirm the +7 comes from git, and construct the "malicious-but-benign-looking" scenario that defeats git-gating — the security nuance this deep-dive turns on.

---

## References

1. **Aider source** — [github.com/Aider-AI/aider](https://github.com/Aider-AI/aider). The primary reference (~25k LOC Python).
2. **Aider Polyglot Benchmark** — the field's de facto coding-agent evaluation.
3. **DD-01 (Pi)** — the thin reference; Aider is +7 via git.
4. **Module 3 — Context Management** — the repo-map as AST-based context.
5. **Modules 4, 8, 9 — Memory, State, Verification** — git as the substrate yielding all three.
6. **Module 6 — Permission** — git-gating as a distinct permission architecture (post-hoc review, not real-time approval).
7. **Module 2 — Tool Design** — the ~8-tool set and why coding-specific tools don't violate the 4-tool philosophy.
8. **Course 2B — OWASP ASI01 / ASI07** — the injection surfaces git-gating does not defend against.