aider-delegate — Claude Code skill: what it does, how to install

---
name: aider-delegate
description: >-
  Delegate a coding task to Aider (`aider`) as a background implementer, then review its diff and land
  it yourself. Use this whenever the user wants to hand implementation work to Aider - phrasings like
  "have Aider do X", "delegate this to aider", "run it through Aider", or "use Aider to
  implement/fix/refactor" - or wants to run a queue of coding tasks through Aider while staying the
  reviewer. This includes asking Aider to drive a local or self-hosted OpenAI-compatible endpoint
  ("have Aider use my local model", "run Aider against llama.cpp / Ollama / vLLM / LM Studio"), which
  Aider reaches via `--api-base`. DO NOT USE for local-model or coding requests that do not name
  Aider, for tasks small enough to do inline, or when the user wants the code written directly
  without delegating.
license: MIT
compatibility: Requires the `aider` CLI (`python -m pip install aider-chat`), Node 18+, and git. Aider must be able to authenticate to a model before dispatch - export the provider key it expects (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …) or set it in Aider's own config; a local OpenAI-compatible endpoint still needs a non-empty `OPENAI_API_KEY`. The orchestrating agent must be able to run shell commands and read files. Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on Windows).
metadata:
  version: 0.5.0
---

# Aider Delegate

You are the **orchestrator**. Hand a bounded coding task to a separate **implementer** - Aider - then
review what it produced and land it yourself. You write the brief and own the judgment; Aider does the
typing in its own run; you verify and commit.

The loop needs only a shell command and file access, so any comparable orchestrator can drive it.

## The one thing to know about Aider

**Aider commits by default.** Two of its defaults would destroy the reviewable diff this skill exists
to produce:

- `--auto-commits` (default `True`) - Aider commits its own edits after each exchange.
- `--dirty-commits` (default `True`) - Aider commits **your** pre-existing uncommitted work before it
  starts editing.

The relay always passes `--no-auto-commits` and `--no-dirty-commits`, and neither is configurable
through it. If you ever drive `aider` by hand instead of through the relay, pass both yourself, or the
work lands as commits you never reviewed. The relay also passes `--no-gitignore`, because Aider
otherwise writes `.aider*` into `.gitignore` on startup and dirties the tree you are about to read.

## When NOT to use this

- The task is small enough to do inline; delegation overhead is not worth it.
- The `aider` CLI is not installed, or no model is configured for it.
- You want the implementer to manage its own commits. Aider can, but this skill deliberately turns
  that off - the diff is the deliverable.

## Prerequisites (check once)

1. Install Aider - `python -m pip install aider-chat`, or the standalone installer from the
   [Aider install docs](https://aider.chat/docs/install.html).
2. Configure a model. Aider reads provider keys from the environment (`OPENAI_API_KEY`,
   `ANTHROPIC_API_KEY`, …) or its own config; see [Aider's model docs](https://aider.chat/docs/llms.html).
3. Confirm `aider --version` succeeds.
4. Work in, or point `--cd` at, the target git repository.

## Choose the model

Aider uses its own configured model when `--model` is omitted. Pass `--model <name>` to pick another.

## Local and self-hosted models

Aider talks to any OpenAI-compatible endpoint, so this is also the skill for delegating to a model
running on the user's own hardware - llama.cpp's server, Ollama, vLLM, LM Studio, or anything else
that serves the same API. Pair `--model` with `--api-base`:

```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo \
  --model openai/<served-model-name> --api-base http://127.0.0.1:<port>/v1
```

Three things differ from a hosted provider:

- **The `openai/` prefix is required.** It tells Aider to speak the OpenAI protocol to your endpoint;
  the part after it is whatever name your server reports, not a provider catalog name.
- **A placeholder key is still needed.** Export any non-empty `OPENAI_API_KEY`. The client library
  requires the header even when the server ignores its value.
- **Ask for a smaller edit format.** Local models often fail Aider's default `diff` format, which
  requires exact search/replace blocks. `--edit-format whole` trades tokens for reliability; keep the
  brief's scope tight with `--file` so whole-file rewrites stay cheap.

A local endpoint that is not running looks like a hang, not an error: Aider retries the connection
until the relay's `--timeout` watchdog fires and reports `status: "timeout"`. Confirm the server is up
before dispatching a long brief.

### Staying offline

No account or provider registration is involved: Aider is a pip install, the endpoint is yours, and
`OPENAI_API_KEY` only has to be non-empty. The relay pins the flags that would otherwise reach the
network on their own - `--no-check-update`, `--no-analytics` (Aider's own default is `random`, which
opts some sessions in by itself), and `--no-detect-urls`, without which Aider offers to scrape any URL
in the brief and `--yes-always` accepts that offer silently.

`--no-suggest-shell-commands` closes the remaining path by which a run could reach the network without
being asked to. What stays outside the relay's control is the brief itself: instructions that tell
Aider to install a package or call an API will still be carried out, and `--auto-lint` runs the
repository's own tooling. Offline here means nothing in the dispatch path reaches out on its own - not
that a sandbox is stopping it.

## The loop

Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.

### 1. Write the brief

Aider sees only the text you send plus the files in its editing scope - no chat history or shared
context. Include the goal, current state, what to change, what to leave untouched, the project's
**actual** gates, and a report contract. Keep one task per brief. See
[references/writing-the-brief.md](references/writing-the-brief.md).

### 2. Dispatch

For **Codex orchestration of background work**, install and configure the separate
**codex-background** support utility first. If its MCP tools or registry are missing, stop and
report the setup requirement; do not silently fall back to model-driven polling. Then invoke its
registered `delegate_run` MCP tool once in place of the shell example below.
Follow that skill for structured common arguments, unchanged provider flags and reattachment by
runId. Keep the request pending until completion, then continue this skill's review and landing
steps. Other orchestrators keep the shell workflow below.

Use the bundled helper. It wraps Aider's headless `--message-file` mode, captures the run, and writes
`result.json`. (`<skill-dir>` is the installed folder containing this `SKILL.md`.)

```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a model:                        add --model <name>
# point at an OpenAI-compatible server:  add --api-base <url>
# scope the edit surface:                add --file <path> (repeatable), --read <path> for context only
# dry run, no files modified:            add --read-only
# continue the previous chat:            add --resume-last  (delta brief only)
# hard time limit (watchdog):            add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# see all options:                       node .../relay.mjs --help
```

The child process's cwd pins the workspace. The brief is delivered with `--message-file`, so it never
rides argv: it stays out of the host process list and clear of the OS argument size cap. The relay
writes artifacts under the system temp dir by default and never commits. See
[references/dispatch-and-poll.md](references/dispatch-and-poll.md).

### 3. Wait for completion

Codex using codex-background keeps the original MCP request pending: no model-driven sleep,
status or log polling. Use `delegate_wait` only to reattach after an interrupted request.

The helper blocks until Aider finishes. Run it with the orchestrator's background-command facility, or
background it in the shell and poll for `result.json`. A pre-run usage error exits 2 and writes no
result; a missing `aider` exits 127 and writes `status: "aider_unavailable"`.

Trust process state and the working tree over a progress display. Completion means the process exited
and `result.json` exists. Aider's report is the `finalMessage` field in `result.json` (also printed in
full on stdout between the report markers).

Aider exits 0 even when it never reached a model, so the relay scans the run for Aider's own endpoint
and authentication errors and reports `status: "failed"` when it finds one. Treat a `failed` status
with an `error` mentioning the endpoint as a configuration problem, not a coding failure.

### 4. Review - do not trust the self-report

Treat Aider's final message and gate claims as claims:

- Re-run the project's gates yourself.
- Read the diff against the brief, starting with `touchedFiles`.
- Run relevant guard skills if installed.
- Round-trip migrations and grep for dangling references after removals or renames.

Aider's `--auto-lint` is on by default, so it may have already run a linter and fixed its own
complaints. That is Aider's lint, not your gates - run yours anyway. See
[references/review-and-land.md](references/review-and-land.md).

### 5. Land it

The implementer edits the working tree; **the orchestrator commits.** Commit only after the gates pass
and the diff holds. If rework is needed, send a delta brief with `--resume-last`, then review again.

## Autonomy and permissions

The relay passes `--yes-always`, Aider's own term for auto-confirming every prompt, because a headless
run cannot answer one. **Understand what that consents to in advance.** Auto-confirmation applies to
every prompt Aider would otherwise raise, and Aider's prompts are not limited to file edits: left at
its defaults it also offers to run shell commands it has suggested, and `--yes-always` would accept
those with nobody reading them. The relay therefore pins `--no-suggest-shell-commands`, which removes
that path.

What remains is not a sandbox, and nothing here pretends otherwise. Aider has no permission modes and
no isolation: within its file scope it edits freely, and `--auto-lint` (on by default) runs whatever
linter the repository configures. A brief that tells Aider to run a command still gets a command run.
Delegation is the authorization; if a run must not be able to touch the host, run it in a container or
a throwaway worktree, because no flag in this relay will give you that.

**File selection is not a security boundary.** `--file`, `--read`, and `--subtree-only` set what Aider
puts in its chat context, which is a scoping and token-cost decision. They do not confine what it can
reach. See [references/writing-the-brief.md](references/writing-the-brief.md).

`--read-only` maps to Aider's `--dry-run`, which performs the run without modifying files. The relay
does not independently verify that claim - it reports what `git status --porcelain` shows and warns if
a `--read-only` run left the tree changed. `touchedFiles` and the diff, not a flag, are the guarantee.

## Resume

Aider has no session ids. Its resume unit is the chat history file it keeps in the repository
(`.aider.chat.history.md`), so `--resume-last` maps to Aider's `--restore-chat-history` and
`--history-file` pins a specific one. Because that history lives in the repo, resume is per-worktree,
not per-user: two clones of the same project do not share it.

## Authorization model

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing
verified, gate-passing work is the agreed contract. Two limits remain: **surface, don't absorb**
(report Aider's design decisions, defensible-but-unasked turns, and non-blocking nitpicks) and **stop
for scope changes** (if correct completion needs going beyond the brief, ask instead of expanding the
mandate). See [references/review-and-land.md](references/review-and-land.md).

## References

- [references/writing-the-brief.md](references/writing-the-brief.md) - structure, report contract,
  real gates, file scope, and delta briefs.
- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) - flags, artifacts,
  `result.json`, polling, and failure recovery.
- [references/review-and-land.md](references/review-and-land.md) - review checklist, the commit
  boundary, and rework through Aider's chat history.
- [references/multi-task-queues.md](references/multi-task-queues.md) - sequential queues, constraint
  carry-forward, progress tracking, and the final coherence pass.