Plugins

built-in adapters

Five adapters ship with Axol. Load order is alphabetical by filename, so claude-code is checked first and zz-generic last. Each card below links to the adapter JSON on GitHub.

where they live

Adapters are plain .json files loaded on startup from two directories, in order:

1. adapters/ next to the axol binary — the five bundled adapters above live here.
2. ~/Library/Application Support/Axol/adapters/ — your own. Drop a file in, restart Axol, done.

Load order is alphabetical by filename within each directory, and the first adapter whose match predicate fires wins. To build a wildcard fallback, name it something like zz-generic.json so it sorts last.

two paths in, one adapter

Axol has two ways to hear about an alert — a local process curl-ing the loopback port, or a webhook riding the remote-alerts bridge. Both paths end at the same place: the adapter registry, which matches on the payload shape and renders the envelope. Plugins are where the two paths converge.

the four stages

Every alert — whether it's a direct envelope POST or a third-party payload routed through an adapter — travels through the same four-stage pipeline on Axol's side:

{
  "workflow_run": {
    "conclusion":  "failure",
    "head_branch": "main",
    "html_url":    "https://github.com/.../runs/42"
  }
}

{
  "match":  { "field": "workflow_run", "exists": true },
  "switch": "workflow_run.conclusion",
  "cases": {
    "failure": {
      "title":    "",
      "body":     "CI failed",
      "priority": "urgent",
      "icon":     "github",
      "actions":  [{ "type": "open-url",
                     "url":  "" }]
    }
  }
}

{
  "title":    "main",
  "body":     "CI failed",
  "priority": "urgent",
  "icon":     "github",
  "actions":  [{ "type": "open-url",
                 "url":  "https://github.com/.../runs/42" }]
}

adapter fields

Each adapter file is a JSON object with these top-level keys:

the match predicate

Every adapter needs a match block that picks whether the incoming payload belongs to it. Supported forms:

{ "field": "workflow_run",         "exists": true }
{ "field": "workflow_run.conclusion", "equals": "failure" }
{ "field": "message",              "matches": "waiting for" }

Dotted paths drill into nested objects. exists fires on any non-null value; equals is exact; matches is a case-insensitive substring. When more than one check is set on the same predicate, all populated conditions must hold (AND). First adapter to match wins.

Skipping specific cases

Any case (or a flat template) can include a skip_if predicate with the same three forms. When it fires, the event is dropped silently instead of rendering — useful for filtering out chatty built-in events (the bundled claude-code.json uses this to swallow the "waiting for your input" notification).

A skipped event is different from a no-match event: it records as "intentionally swallowed" in NSLog, so you can tell "my filter fired" apart from "no adapter claimed this payload."

Loud validation at load time

Adapter files are validated when Axol starts. Unknown top-level keys (typo'd swtich or stray temlate), unknown predicate keys (e.g. match_es, eqals), and wrong-typed values all cause the adapter to be rejected with a NSLog line naming the offending key. You'll see this in Console.app — silent "my adapter just doesn't work" was the old behaviour and has been retired.

switch + cases vs flat template

Two ways to ship an envelope from an adapter, depending on whether one incoming payload shape maps to one alert or to several:

Flat template

Use when the match fires and you always want the same envelope shape. Single template object at the top level:

{
  "name":     "generic",
  "match":    { "field": "title", "exists": true },
  "template": {
    "title":  "",
    "body":   "",
    "icon":   ""
  }
}

Switch + cases

Use when one source's payload can mean different things — e.g. GitHub's workflow_run emits success / failure / cancelled conclusions that deserve different priorities and copy. The switch value picks the case by exact string match:

{
  "match":  { "field": "workflow_run", "exists": true },
  "switch": "workflow_run.conclusion",
  "cases": {
    "success":  { "title": "", "body": "CI passed", "priority": "normal", "icon": "github" },
    "failure":  { "title": "", "body": "CI failed", "priority": "urgent", "icon": "github" },
    "cancelled":{ "title": "", "body": "CI cancelled", "priority": "low",    "icon": "github" }
  }
}

If the switch field resolves to a value that doesn't appear as a case key, nothing renders for that event — silently dropped like a missed match. Add a wildcard by naming a case whatever string your field will commonly produce, or pair with a fallback adapter sorted later in the directory.

template language

Every string value in a template runs through a tiny substitution engine. Whole strings that are just preserve their native type (so "pid": "" yields "pid": 12345, not "12345").

default icon set

Set icon on the envelope to one of these names and Axol renders the matching glyph in the speech bubble. Most names resolve to SF Symbols; claude and github are bundled Bootstrap Icons SVGs. Unknown strings fall through as a literal prefix, so "icon": "🚢" still works for quick one-offs.

action vocabulary

Actions are a closed set. Unknown action types are silently dropped by the envelope validator — adapters can't invent new ones.

{ "type": "focus-pid",    "pid": 12345,               "label": "Open terminal" }
{ "type": "open-url",     "url": "https://…",         "label": "View run" }
{ "type": "reveal-file",  "path": "/Users/me/…",      "label": "Open in Finder" }
{ "type": "noop",                                     "label": "Dismiss" }

open-url is restricted to http:// and https://; reveal-file paths must exist and live inside $HOME. The first action in the envelope is what fires when the bubble is clicked.

end-to-end example: GitHub Actions

Wiring GitHub Actions to Axol end-to-end, using the remote-alerts bridge:

1. Create the adapter

Save as ~/Library/Application Support/Axol/adapters/github.json:

{
  "name":   "github-ci",
  "match":  { "field": "workflow_run", "exists": true },
  "switch": "workflow_run.conclusion",
  "cases": {
    "success": {
      "title":    "",
      "body":     "CI passed",
      "priority": "normal",
      "icon":     "github",
      "source":   "github-ci",
      "actions":  [{ "type": "open-url", "url": "", "label": "View run" }]
    },
    "failure": {
      "title":    "",
      "body":     "CI failed",
      "priority": "urgent",
      "icon":     "github",
      "source":   "github-ci",
      "actions":  [{ "type": "open-url", "url": "", "label": "View run" }]
    }
  }
}

2. Point GitHub at your neuromast

In the GitHub repo's Settings → Webhooks, add your neuromast's public URL — e.g. https://<your-neuromast>/app/api/hooks/github. Set the content type to application/json and copy the webhook secret into HOOK_SECRET_GITHUB on the neuromast environment (see the deploy guides).

3. Push something

Next failed workflow run pops an urgent pink bubble on your desktop with the GitHub mark and a "View run" action. No code written, one file added.

share your adapter

If you wrote an adapter for a service other people use, open a PR — we'll bundle it. Adapters are declarative JSON with a closed action vocabulary, so review is shallow and turnaround is fast.

1. Write it against a real payload. Capture a live sample (from the service's webhook logs, or request.body in a local dev tunnel), save it to fixture.json, and run your template against it with jq or by POSTing to Axol's loopback port. If the bubble says what you want, ship it.
2. Name it after the source. linear.json, datadog.json, vercel.json. Use a zz- prefix only for catch-alls that should sort last.
3. Open a PR on GitHub. Drop the file in axol/adapters/. Include a sanitized sample payload in the PR description (strip emails, IDs, tokens) and a one-liner on which webhook event you captured it from.
4. Review checklist — the four things we look at, in order:
   • Does match fire only for that source? No overlap with existing built-ins.
   • Is urgent reserved for genuinely actionable events? Chatty events should be normal or low.
   • Do all templated fields have a | default fallback where the source field is optional?
   • Any open-url action — does the URL resolve to a useful page for the alert?