You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/09/19 13:47:25 UTC
(magpie) branch main updated: feat(adapter/aider): Aider agent harness runtime guide (#1286)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new ec64b811 feat(adapter/aider): Aider agent harness runtime guide (#1286)
ec64b811 is described below
commit ec64b811291e32ed1cb1c54194c23cd4fcdf817d
Author: Vardhman Gupta <11...@users.noreply.github.com>
AuthorDate: Sat Sep 19 19:17:20 2026 +0530
feat(adapter/aider): Aider agent harness runtime guide (#1286)
* feat(adapter/aider): Aider agent harness runtime guide
* fix(adapter/aider): address maintainer review feedback on Aider harness guide (#317)
* docs(adapters): name Aider's in-chat command `/read-only`
`/read` only works as a prefix match; the documented command is
`/read-only` (the `--read` flag is unchanged).
Generated-by: Claude Code (Fable 5.1)
---------
Co-authored-by: Jarek Potiuk <po...@apache.org>
---
CONTRIBUTING.md | 2 +-
docs/adapters/README.md | 12 +-
docs/adapters/aider.md | 233 ++++++++++++++++++++++++++++++++++++++
docs/adapters/registry.md | 2 +-
docs/quick-start/prerequisites.md | 3 +
docs/vendor-neutrality.md | 4 +-
6 files changed, 249 insertions(+), 7 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9888a5fb..d8a10d65 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -395,7 +395,7 @@ authoritative agent harness matrix. The current state per harness:
| Gemini CLI | Experimental agent harness: native skills, action guard, runner, tool sandboxing and approval policies; sandbox parity gaps remain — see the [harness guide](docs/adapters/gemini.md) | [#314](https://github.com/apache/magpie/issues/314) |
| Local LLM (Ollama / llama.cpp / vLLM) | OpenAI-compatible endpoints with calibrated model floors (70B+ / 8B–14B) — see the [harness guide](docs/adapters/local-llm.md) | [#315](https://github.com/apache/magpie/issues/315) |
| Cursor (Composer + Agent CLI) | Reads `.agents/skills/` natively; per-action confirmation and Composer/Agent CLI — see the [harness guide](docs/adapters/cursor.md) | [#316](https://github.com/apache/magpie/issues/316) |
-| Aider | Not yet ported | [#317](https://github.com/apache/magpie/issues/317) |
+| Aider | Multi-model terminal pair programming CLI; per-action confirmation and on-demand skill ingestion — see the [harness guide](docs/adapters/aider.md) | [#317](https://github.com/apache/magpie/issues/317) |
| GitHub Copilot CLI + Coding Agent | Not yet ported | [#318](https://github.com/apache/magpie/issues/318) |
| Goose (Block) | Open-source agent CLI; reads `.agents/skills/` natively, developer tool execution, and recipe workflows — see the [harness guide](docs/adapters/goose.md) | [#319](https://github.com/apache/magpie/issues/319) |
| Amazon Q Developer CLI | Not yet ported | [#320](https://github.com/apache/magpie/issues/320) |
diff --git a/docs/adapters/README.md b/docs/adapters/README.md
index 13e1ab15..94eded1f 100644
--- a/docs/adapters/README.md
+++ b/docs/adapters/README.md
@@ -28,10 +28,12 @@ section is the map of what exists and how to add what does not.
One page per supported agentic harness, each declaring
`capability:platform`:
+- [**Aider**](aider.md) — terminal pair programming agent harness.
- [**Codex**](codex.md) — first-class harness.
- [**Cursor**](cursor.md) — Composer and the Agent CLI.
- [**Gemini CLI**](gemini.md) — extension install, `BeforeTool` guard, tool
sandboxing and policies. Experimental.
+- [**Goose**](goose.md) — Block's open-source agent CLI and desktop environment.
- [**Kiro CLI**](kiro.md) — per-skill installs, no marketplace; guard on
`preToolUse`.
- [**Local LLM**](local-llm.md) — Ollama, llama.cpp, vLLM.
@@ -41,7 +43,7 @@ One page per supported agentic harness, each declaring
Not the same thing, and the differences matter more than the similarities.
Every harness gets the clean-environment layer; the action guard reaches four
-of six.
+of eight.
| Harness | Clean environment | Filesystem sandbox | Action guard |
|---|---|---|---|
@@ -51,13 +53,15 @@ of six.
| **Kiro CLI** | `kiro-iso` | from the OS-level sandbox | ✅ `preToolUse` |
| **OpenAI Codex CLI** | `agent-iso codex` | Codex's own sandbox and exec policy, statically validated by [sandbox-lint](../../tools/sandbox-lint/README.md) | ❌ **none** |
| **Cursor** | `agent-iso cursor` | Cursor's own policy | ❌ **none** |
+| **Goose (Block)** | `agent-iso goose` | Goose developer mode / approval prompts | ❌ **none** |
+| **Aider** | `agent-iso aider` | Aider's own policy / git repository map | ❌ **none** |
**What the last column costs.** The action guard is what deterministically
refuses a command that would break a hard framework rule — pinging maintainers,
a `Co-Authored-By` trailer, `--no-verify`, marking a PR ready prematurely,
-emptying a PR by force-push. On Codex and Cursor those rules are instructions
-the model is asked to follow, not a gate that stops it. Both harnesses have
-their own approval prompts, and neither knows Magpie's rules.
+emptying a PR by force-push. On Codex, Cursor, Goose, and Aider those rules are instructions
+the model is asked to follow, not a gate that stops it. These harnesses have
+their own approval prompts, and none of them know Magpie's rules out of the box.
That is a gap in the framework, not in those tools: `agent-guard`'s core is
harness-neutral and each supported harness needed only a thin adapter. See
diff --git a/docs/adapters/aider.md b/docs/adapters/aider.md
new file mode 100644
index 00000000..bea56506
--- /dev/null
+++ b/docs/adapters/aider.md
@@ -0,0 +1,233 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read-only` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not include a Model Context Protocol (MCP) client; deterministic operations execute through local CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider does not discover skills on its own; load the one you need with `/read-only` or `--read` (see below).
+
+### Interactive terminal session
+
+Start an interactive session within the adopted repository:
+
+```bash
+# Launch Aider with filtered environment variables and disabled auto-commits
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits --no-dirty-commits
+```
+
+### Progressive skill disclosure
+
+To prevent context-window exhaustion across Magpie's 70+ workflows, load only the specific skill required for the current task:
+
+```text
+/read-only .agents/skills/magpie-security-issue-triage/SKILL.md
+```
+
+Inside the session, prompt Aider to execute the workflow:
+
+```text
+Follow the procedure in the loaded SKILL.md to triage inbound report #<issue-number>.
+Adhere strictly to proposal-then-confirm discipline before applying any tracker mutations.
+```
+
+Aider reads the loaded `SKILL.md`, checks prerequisites, and presents proposed diagnostic steps before taking action.
+
+### Headless or automated execution
+
+For non-interactive triage passes, automated sweeps, or headless scripting:
+
+```bash
+# Headless run using an explicit instruction text (-m) and target skill file
+aider --model <model> \
+ --read .agents/skills/magpie-list-skills/SKILL.md \
+ --message "Execute the loaded list-skills procedure and summarize available workflows." \
+ --no-auto-commits
+```
+
+## Configuration and repository instructions
+
+### Repository configuration (`.aider.conf.yml`)
+
+Configure repository defaults in `.aider.conf.yml` at the repository root to ensure all team members operate under Magpie's safety baseline:
+
+```yaml
+# .aider.conf.yml
+# 1. Enforce Human-in-the-loop confirmation
+auto-commits: false
+dirty-commits: false
+
+# 2. Ingest repository safety instructions
+read:
+ - AGENTS.md
+
+# 3. Model parameters (optional adopter defaults)
+# model: <model>
+# edit-format: diff
+```
+
+### Protecting private and local state (`.aiderignore`)
+
+Aider automatically constructs a repository map (repomap) to track codebase structure.
+To prevent Aider from reading private adopter tokens, test fixtures, or local overrides into the prompt context, configure `.aiderignore` at the repository root:
+
+```text
+# .aiderignore
+.env*
+*.key
+*.pem
+*.token
+```
+
+## Tool bridges and subshell execution
+
+Magpie skills execute deterministic operations via language-agnostic scripts under `tools/` (e.g. `tools/cve-tool-vulnogram/`, `tools/github/`, `tools/privacy-llm/`).
+
+When a skill requires running a tool command:
+- The operator or model proposes the subshell command (e.g. `gh issue view <issue-number> --repo <tracker>`).
+- In an interactive session, execute the command directly via `/run <cmd>` or `!<cmd>`.
+- Actions execute in the local project environment following standard subshell semantics.
+
+## Human-in-the-loop and git confirmation
+
+Magpie enforces strict [Human-in-the-Loop principles](../rfcs/RFC-AI-0004.md): no destructive action or git state mutation occurs without explicit human approval.
+
+> [!IMPORTANT]
+> **Aider auto-commit policy:** By default, Aider automatically commits every code modification to git.
+>
+> In Magpie adopted repositories, adopters **must disable auto-commits** either via CLI flags:
+> ```bash
+> aider --no-auto-commits --no-dirty-commits
+> ```
+> or via `.aider.conf.yml`:
+> ```yaml
+> auto-commits: false
+> dirty-commits: false
+> ```
+
+When operating with auto-commits disabled:
+- **Diff review:** Review proposed file changes using `git diff` or in-session `/diff` before staging.
+- **Explicit commit gating:** Use `/commit` only after confirming the change satisfies review criteria.
+- **Write-access discipline:** Outbound communications, issue state changes (`gh issue close`), and remote pushes (`git push`) must always remain gated on explicit human confirmation.
+
+## Multi-model routing and model floors
+
+Aider supports multi-provider model routing, allowing adopters to calibrate model power against task complexity per [docs/mode-economics.md](../mode-economics.md).
+
+### Architect and editor model split
+
+For complex triage and vulnerability assessment, use Aider's `--architect` mode to separate high-level reasoning from code editing:
+
+```bash
+# Reasoning model handles analysis; fast editor applies diffs
+aider --architect \
+ --model <reasoning-model> \
+ --editor-model <editor-model> \
+ --no-auto-commits
+```
+
+### Local LLM connectivity (Ollama / vLLM)
+
+For sovereign or air-gapped deployments where data cannot leave the local host (see [docs/adapters/local-llm.md](local-llm.md)):
+
+```bash
+# Connect Aider to a local Ollama instance
+export OLLAMA_API_BASE=http://127.0.0.1:11434
+aider --model ollama_chat/<model> \
+ --no-auto-commits
+```
+
+## Clean-environment wrapper and isolation
+
+To run Aider under Magpie's standard credential isolation policy:
+
+```bash
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits
+```
+
+The `agent-iso` launcher scrubs ambient cloud tokens while preserving local developer tooling (`git`, `uv`, `gh`, `aider`).
+
+> [!WARNING]
+> **Layer 0 Isolation Caveat:** As documented in [`tools/agent-isolation/README.md`](../../tools/agent-isolation/README.md), generic harness invocations (`agent-iso <cli>`) provide **Layer 0 environment stripping only — no push gate**. Aider receives the live `SSH_AUTH_SOCK` with nothing gating a `git push` at the wrapper boundary. Gating remote pushes relies on operating with `--no-auto-commits` and operator diligence.
+
+## Verify
+
+Verify that the Aider harness wiring conforms to framework standards:
+
+```bash
+# 1. Verify skill discovery topology
+PYTHONUTF8=1 uv run --project tools/symlink-lint symlink-lint
+
+# 2. Validate skill and tool metadata
+PYTHONUTF8=1 uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate
+
+# 3. Check vendor neutrality score
+PYTHONUTF8=1 uv run --project tools/vendor-neutrality-score vendor-neutrality-score
+
+# 4. Check documentation table of contents and formatting
+uv run prek run doctoc --all-files
+```
+
+## See also
+
+- [`docs/rfcs/RFC-AI-0004.md`](../rfcs/RFC-AI-0004.md) — normative principles for vendor neutrality and open-source harnesses.
+- [`docs/vendor-neutrality.md`](../vendor-neutrality.md) — framework vendor neutrality index across agent harnesses.
+- [`docs/adapters/local-llm.md`](local-llm.md) — running open-weight models via local inference engines.
+- [`docs/adapters/goose.md`](goose.md) — Block's Goose agent harness guide.
+- [`docs/adapters/add-a-harness.md`](add-a-harness.md) — step-by-step guide for integrating agent harnesses.
+- [`tools/agent-isolation/README.md`](../../tools/agent-isolation/README.md) — clean-environment launcher.
+- [Aider documentation](https://aider.chat/) — official Aider installation and usage guides.
diff --git a/docs/adapters/registry.md b/docs/adapters/registry.md
index 74350315..cf40a37e 100644
--- a/docs/adapters/registry.md
+++ b/docs/adapters/registry.md
@@ -55,7 +55,7 @@ extension point = a documented, labelled slot with a tracking issue.
| [`tools/scan-format`](../../tools/scan-format/) | ASVS | other scanner formats |
| [`tools/vcs`](../../tools/vcs/) | Git, Mercurial, Fossil | Subversion [\#602](https://github.com/apache/magpie/issues/602), Jujutsu [\#603](https://github.com/apache/magpie/issues/603), Perforce [\#605](https://github.com/apache/magpie/issues/605) |
| Forge / tracker | [`github`](../../tools/github/), [`jira`](../../tools/jira/), [`bitbucket`](../../tools/bitbucket/) `partial-read-only` foundation, [`sourcehut`](../../tools/sourcehut/), [`fossil`](../../tools/fossil/) | GitLab [\#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [\#310](https://github.com/apache/magpie/issues/310), Pagure [\#312](https://github.com/apache/magpie/issues/312), deeper Bitbucket/Jira coverage [\#606](https://github.com/apache/magpie/issue [...]
-| Agent harness | Claude Code, [Codex](codex.md) `experimental` ([#313](https://github.com/apache/magpie/issues/313)), [Gemini CLI](gemini.md) `experimental` ([#314](https://github.com/apache/magpie/issues/314)), [Local LLM (Ollama / llama.cpp / vLLM)](local-llm.md) ([#315](https://github.com/apache/magpie/issues/315)), [Cursor](cursor.md) ([#316](https://github.com/apache/magpie/issues/316)), [Goose](goose.md) `guide only` ([#319](https://github.com/apache/magpie/issues/319)) | Aider [# [...]
+| Agent harness | Claude Code, [Codex](codex.md) `experimental` ([#313](https://github.com/apache/magpie/issues/313)), [Gemini CLI](gemini.md) `experimental` ([#314](https://github.com/apache/magpie/issues/314)), [Local LLM (Ollama / llama.cpp / vLLM)](local-llm.md) ([#315](https://github.com/apache/magpie/issues/315)), [Cursor](cursor.md) ([#316](https://github.com/apache/magpie/issues/316)), [Goose](goose.md) `guide only` ([#319](https://github.com/apache/magpie/issues/319)), [Aider](a [...]
| Security cross-ref | — | OSV.dev [#311](https://github.com/apache/magpie/issues/311) |
## In-tree organizations
diff --git a/docs/quick-start/prerequisites.md b/docs/quick-start/prerequisites.md
index b86b6595..8c75e828 100644
--- a/docs/quick-start/prerequisites.md
+++ b/docs/quick-start/prerequisites.md
@@ -79,6 +79,9 @@ on any single vendor for either — any agent that reads the shared
- **[Goose](https://github.com/block/goose)** is an open-source agent CLI that reads
Magpie's canonical `.agents/skills/` tree natively and supports recipe workflows;
see [the Goose harness guide](../adapters/goose.md).
+- **[Aider](https://aider.chat/)** is an open-source, multi-model terminal pair programming CLI
+ with per-action confirmation and native local/cloud model support;
+ see [the Aider harness guide](../adapters/aider.md).
Support for more runtimes (Copilot, …) is tracked in
the
diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md
index 25796413..bffdbca4 100644
--- a/docs/vendor-neutrality.md
+++ b/docs/vendor-neutrality.md
@@ -328,9 +328,11 @@ OpenAI-compatible endpoints with calibrated capability floors; see the
Goose is an open-source agent CLI that reads `.agents/skills/` natively and supports
recipe workflows and developer tool execution; see the
[Goose harness guide](adapters/goose.md).
+Aider is an open-source terminal pair programming CLI with per-action confirmation,
+multi-model routing, and local LLM support; see the
+[Aider harness guide](adapters/aider.md).
The remaining extension points are
already open, labelled `good first issue`:
-[Aider](https://github.com/apache/magpie/issues/317),
[GitHub Copilot](https://github.com/apache/magpie/issues/318),
[Amazon Q](https://github.com/apache/magpie/issues/320),
[JetBrains Junie](https://github.com/apache/magpie/issues/321),