# Connect Goose to Axiom

**Transport:** stdio (Goose also supports HTTP-SSE)
**Auth:** local-stdio (Phase 0)
**Status:** Untested — recipe inferred from upstream docs

Goose is Block's open-source agent harness. It treats MCP servers as
"extensions" (Goose's own terminology, not AEOS extensions). Config lives
at `~/.config/goose/config.yaml` plus optional per-extension files.

## Install prerequisites

- Goose CLI: `curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | sh`
  (or via the Goose Desktop app installer).
- Same Axiom prerequisites as the other recipes.

## Configure the connection

Add an `extensions` block to `~/.config/goose/config.yaml`:

```yaml
extensions:
  axiom-root:
    enabled: true
    type: stdio
    cmd: /absolute/path/to/.venv/bin/axi
    args:
      - mcp
      - serve
    timeout: 300
    description: Axiom node (memory + federation + RAG + signals + extensions)
```

Worktree variant (uninstalled package):

```yaml
extensions:
  axiom-root:
    enabled: true
    type: stdio
    cmd: /absolute/path/to/.venv/bin/python3
    args:
      - -m
      - axiom.extensions.builtins.mcp.server
    envs:
      PYTHONPATH: /absolute/path/to/axiom-checkout/src
    timeout: 300
```

Alternatively, use the Goose UI: `goose configure -> Add Extension ->
Command-line Extension` and paste the same command/args.

## Verify

```bash
$ goose session
> /extensions
```

`axiom-root` should be listed as enabled. From the session prompt:

```
> Run the axiom_node__hooks_list tool with no arguments and show me the result.
```

Expected output (rendered through Goose's tool-call view):

```json
{
  "node": "/Users/<you>/.axiom",
  "hooks_total": 0,
  "events_observed": [],
  "by_event": {}
}
```

## Notes

- Goose has a built-in approval prompt for each tool call on first use.
  Tools annotated as `side_effects = "writes"` or `"external"` will
  always prompt; safe-read tools can be approved-always.
- Goose Desktop and CLI share `~/.config/goose/config.yaml`, so a single
  block enables the connection for both.
- Goose supports HTTP-SSE via `type: sse` and a `url` field. That path
  needs Axiom's Phase 5 auth (`axi mcp serve --http`); not available
  yet.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `Extension not found` | typo in `cmd` path | Use absolute path; `which axi` to confirm |
| Tools missing | extension started but PYTHONPATH wrong | Add `envs.PYTHONPATH` |
| Goose hangs on launch | server crashes on startup | Run the `cmd` manually; check `~/.axiom/logs/mcp/server.log` |

## References

- ADR-038 §D7
- Goose extensions docs: https://block.github.io/goose/docs/getting-started/using-extensions

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