# Connect Aider to Axiom

**Transport:** stdio (via shell-bridge fallback today; native MCP tracked upstream)
**Auth:** local-stdio (Phase 0)
**Status:** Pending upstream — Aider does not ship a first-party MCP client as of 2026-Q2

Aider is Paul Gauthier's terminal-native pair-programming agent. Its
plugin model is Python-import based, not MCP-spec based. Native MCP
support is on the roadmap but not shipped at the time of writing; this
recipe documents the bridge-via-shell pattern so you can use Axiom's
tools from Aider today.

## Install prerequisites

- Aider 0.74 or later (`pip install aider-chat`).
- Same Axiom prerequisites as the other recipes.

## Configure the connection (bridge fallback)

Aider supports loading external commands as `/run` shortcuts. Add
shortcuts to your project's `.aider.conf.yml`:

```yaml
shortcuts:
  axiom-tools: "axi mcp list-tools"
  axiom-status: "axi mcp status"
  axiom-hooks: |
    axi mcp inspect axiom_node__hooks_list && \
    echo '{}' | axi mcp call axiom_node__hooks_list
```

(The `axi mcp call <tool>` form reads JSON args from stdin and prints
the JSON result; this is the v1 stdio-bridge equivalent of an MCP
client.)

Or, for a project-wide alias, drop a small wrapper into your `$PATH`:

```bash
#!/usr/bin/env bash
# ~/bin/axi-mcp-call
exec axi mcp call "$@"
```

In Aider, you can then `/run axi-mcp-call axiom_node__hooks_list <<< '{}'`.

## Verify

```bash
$ axi mcp call axiom_node__hooks_list <<< '{}'
{
  "node": "/Users/<you>/.axiom",
  "hooks_total": 0,
  "events_observed": [],
  "by_event": {}
}
```

Inside Aider:

```
> /run axi-mcp-call axiom_node__hooks_list <<< '{}'
```

The same JSON appears in the chat context; Aider can now reason about
its content.

## Notes

- This is a shell-bridge, not a real MCP client integration. Aider sees
  text output, not structured tool-call results, so the model has to
  parse the JSON itself. Acceptable for diagnostic and read-only flows;
  rough for write-heavy workflows.
- Track upstream for native MCP: https://github.com/Aider-AI/aider — at
  the time of writing, the maintainers have indicated MCP is on the
  consideration list but no commitment.
- When Aider does ship native MCP support, this recipe will be updated
  to point at the same `axiom-root` stdio entry the other Tier-1 harnesses
  use.

## What we'd need upstream

For first-class support, Aider would need to add MCP-client capability
(spec compliant — initialize, list_tools, call_tool over stdio) and a
config block analogous to Cline / Continue.dev. Filing the feature
request upstream is the right next step.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `axi: command not found` | venv not activated in shell | Activate venv, or use absolute path in shortcut |
| JSON parse error in Aider | tool returned plain text | Tools always return valid JSON; check `axi mcp call` exit code |
| Output too long | hits Aider's context limit | Filter via `jq` in the shortcut command |

## References

- ADR-038 §D7
- Aider docs: https://aider.chat
- MCP spec: https://modelcontextprotocol.io

_Copyright (c) 2026 B-Tree Ventures, LLC. Apache-2.0 licensed._
