Integrations

Works with what you already have.

Every integration below shows three things: who it’s for, how it authenticates, and exactly what steps to take. Pick the closest match to your stack, follow the numbered steps, ship.

chirp login

Run once, every SDK reads the saved credentials from ~/.chirprc.

env var

API key env var

You set CHIRP_API_KEY in a CI secret, shell profile, or .env file.

signed URL

Paste a URL (with ?key=...) into another service's webhook field.

SDKs

Import, call, forget.

Python SDK

ML training loops, Rake-style scripts, AI agents.

Decorator + context-manager. The most common path for long-running Python work — training runs, scrapers, data pipelines.

Livechirp login

Setup

1pip install chirp-sdk
2chirp login (if you haven't yet)
3Import track or ChirpAgent and call it in your code

train.py

from chirp import track

@track("model training", theme="#818cf8")
def train():
    for epoch in range(10):
        train_one_epoch()

train()  # phone shows a Live Activity for the whole call

Node SDK

Node workers, Next.js build tasks, Deno/Bun scripts.

Zero-dep TypeScript/JavaScript client. track() wrapper, ChirpAgent callback form, and Express error middleware.

Livechirp login

Setup

1npm install chirp
2chirp login (if you haven't yet)
3Import { track } from 'chirp' and wrap any async function

deploy.ts

import { track } from 'chirp';

const deploy = track({ name: 'deploy', theme: '#22c55e' }, async (env: string) => {
  await build();
  await push(env);
});

await deploy('prod');  // green on return, red on throw

Go SDK

Backend services, devops tools, anything written in Go.

Zero-dependency Go package. Track() wrapper mirrors the Python and Node SDKs — same ergonomics, no goroutines in your face.

Livechirp login

Setup

1go get github.com/BradyMeighan/ChirpApp/go-sdk
2chirp login (so the SDK reads ~/.chirprc)
3Call chirp.Track(ctx, opts, fn) from your code

main.go

import chirp "github.com/BradyMeighan/ChirpApp/go-sdk"

err := chirp.Track(ctx, chirp.AgentOptions{Name: "backup"}, func(a *chirp.Agent) error {
    a.Update(ctx, "dumping postgres")
    return backup()
})

Rust SDK

Systems services, ML infra, Rust CLIs.

Blocking Rust client — same lifecycle model as the other SDKs. Use tokio::task::spawn_blocking if you're async.

Livechirp login

Setup

1cargo add chirp
2chirp login
3use chirp::track; then wrap any closure

main.rs

use chirp::{track, AgentOptions};

track(AgentOptions::new("train").theme("#22c55e"), |agent| {
    agent.update("epoch 1/10")?;
    Ok::<_, anyhow::Error>(())
})?;

Ruby gem

Rails ActiveJobs, Sidekiq workers, Rake tasks.

Pure Ruby, zero runtime deps. Blocks stay ergonomic — Chirp.track { |agent| ... } handles the whole lifecycle.

Livechirp login

Setup

1gem install chirp (or add to Gemfile)
2chirp login
3require 'chirp'; Chirp.track(name: '...') { |a| ... }

backup_job.rb

require "chirp"

Chirp.track(name: "nightly backup") do |agent|
  agent.update("dumping postgres")
  Backup.run!
  agent.update("uploading to S3")
  S3.upload!
end

pytest plugin

Run a test suite on your phone — see passes/fails tick live.

Ships as an entry point in the Python SDK. Opt-in per-run with --chirp or CHIRP_PYTEST=1. Costs zero when unused.

Livechirp login

Setup

1pip install chirp-sdk
2chirp login
3pytest --chirp (or set CHIRP_PYTEST=1 once)

shell

pip install chirp-sdk
chirp login
pytest --chirp

Express / Connect

Any Node web server — page yourself the moment a 5xx leaks.

One-line error middleware. Never blocks a request on Chirp transport; swallows failures so a dead Chirp can never worsen an incident.

Liveenv var

Setup

1npm install chirp
2Add CHIRP_API_KEY to your server's env (via .env, Kubernetes secret, Railway var, etc.)
3app.use(chirpErrorNotifier({ service: 'your-service' }))

typescript

import { chirpErrorNotifier } from 'chirp/express';

app.use(/* routes */);
app.use(chirpErrorNotifier({ service: 'api' }));

MCP server

AI assistants that speak the Model Context Protocol.

Tools: activity_start, activity_update, activity_end, notify, template_list. Drop into Claude Desktop or any MCP client.

Liveenv var

Setup

1Add CHIRP_API_KEY to your shell env (or to the MCP client's config)
2Register the server in your MCP client's config
3Reload — the chirp tools appear

shell

# Claude Desktop → claude_desktop_config.json:
{
  "mcpServers": {
    "chirp": {
      "command": "npx",
      "args": ["@chirp/mcp-server"],
      "env": { "CHIRP_API_KEY": "chirp_sk_..." }
    }
  }
}

CLI & shell

Install once, wrap anything that exits.

CLI — chirp run

Any command that already exists — no code changes.

Wraps any shell command in a Live Activity lifecycle. Green on exit 0, red on non-zero. Works with anything that exits.

Livechirp login

Setup

1curl -fsSL https://chirpapp.dev/install.sh | bash (installs the CLI)
2chirp login
3chirp run -s @schema -- your-command-here

shell

chirp run -s @deploy   -n "prod deploy" -- ./deploy.sh
chirp run -s @training -n "GPT sweep"   -- python train.py
chirp run -s @build    -n "iOS archive" -- xcodebuild archive -scheme MyApp

Bash helpers

Cron jobs, systemd services, Makefile recipes, Docker entrypoints.

Source one file, get chirp_notify / chirp_wrap / chirp_start functions. Pure curl, no deps — runs on Alpine.

Liveenv var

Setup

1curl -fsSL https://chirpapp.dev/connectors/bash/chirp.sh -o ~/.chirp.sh
2Set CHIRP_API_KEY in env (env file for systemd, repo secret for CI, or shell rc)
3source ~/.chirp.sh → chirp_notify / chirp_wrap / chirp_start are available

shell

source ~/.chirp.sh
chirp_notify "Deploy done" "my-app live"
chirp_wrap @deploy "nightly" -- ./deploy.sh

CLI — chirp tail

See everything Chirp is doing, live, in your terminal.

Live-follows your account's activity + notification logs. Useful for debugging a webhook, watching a deploy, or confirming a key works.

Livechirp login

Setup

1Install the CLI and run chirp login (if you haven't yet)
2chirp tail
3Pipe to jq for structured output: chirp tail --json | jq

shell

chirp tail
chirp tail --json    # machine-readable, pipe to jq

CI / CD

Same story across every major CI service.

GitHub Actions

Push CI status to your phone while you grab coffee.

Composite action — pure bash + curl, no Docker pull. Errors are warnings so Chirp never fails a build.

Liveenv var

Setup

1GitHub repo → Settings → Secrets and variables → Actions → add CHIRP_API_KEY (copy your key from the dashboard)
2Add uses: chirp/chirp-action@v1 steps to your workflow
3Reference the secret: api-key: ${{ secrets.CHIRP_API_KEY }}

.github/workflows/deploy.yml

- uses: chirp/chirp-action@v1
  with:
    api-key: ${{ secrets.CHIRP_API_KEY }}
    action: start
    schema: '@deploy'
    data: '{"repo":"${{ github.repository }}","stage":"build","progress":0}'

- run: npm ci && npm run build

- uses: chirp/chirp-action@v1
  if: always()
  with:
    api-key: ${{ secrets.CHIRP_API_KEY }}
    action: end
    schema: '@deploy'
    data: '{"stage":"done","progress":1}'

Docs →

GitLab CI

Self-hosted GitLab or gitlab.com — same CI story as GitHub.

Include the remote template, extend `.chirp` in any job. Shell functions become available on any runner with curl.

Liveenv var

Setup

1GitLab project → Settings → CI/CD → Variables → add CHIRP_API_KEY (masked + protected)
2Add include: remote: https://chirpapp.dev/connectors/gitlab-ci/chirp.gitlab-ci.yml to your .gitlab-ci.yml
3Extend .chirp in any job and call chirp_send

.gitlab-ci.yml

include:
  - remote: https://chirpapp.dev/connectors/gitlab-ci/chirp.gitlab-ci.yml

deploy:
  extends: .chirp
  script:
    - !reference [.chirp_send_start, script]
    - ./deploy.sh
    - !reference [.chirp_send_end,   script]

CircleCI

Teams running CircleCI — drop-in orb, no publishing required.

Inline orb with `chirp/send` command. Reference the URL directly until it's on CircleCI Orb Hub.

Liveenv var

Setup

1CircleCI → Project Settings → Environment Variables → add CHIRP_API_KEY
2Add the orb reference to your .circleci/config.yml
3Use chirp/send steps in any job

.circleci/config.yml

orbs:
  chirp: { url: https://chirpapp.dev/connectors/circleci/orb.yml }

jobs:
  deploy:
    docker: [{ image: cimg/node:20 }]
    steps:
      - checkout
      - chirp/send:
          action: start
          schema: "@deploy"
          data: '{"stage":"build"}'
      - run: ./deploy.sh
      - chirp/send:
          action: end
          schema: "@deploy"
          data: '{"stage":"done"}'

Bitbucket Pipelines

Atlassian shops — same CI story via bash helpers.

No dedicated pipe — one `source <(curl ...)` line per step gives you chirp_* functions. Simpler than a Docker image.

Liveenv var

Setup

1Bitbucket repo → Settings → Repository variables → add CHIRP_API_KEY (secured)
2In any pipeline step, source the bash helpers at the top
3Call chirp_start / chirp_update / chirp_end / chirp_notify

bitbucket-pipelines.yml

pipelines:
  default:
    - step:
        script:
          - source <(curl -fsSL https://chirpapp.dev/connectors/bash/chirp.sh)
          - chirp_wrap @deploy "prod" -- ./deploy.sh

Docker

Containerized services — send status without adding a runtime.

Fragment for any Dockerfile that installs the bash helpers. Works in Alpine, Debian, Ubuntu.

Liveenv var

Setup

1Add the RUN snippet to your Dockerfile (installs curl + chirp.sh)
2At container runtime, set CHIRP_API_KEY in env (Docker secret, --env-file, compose)
3In your entrypoint, . /usr/local/share/chirp.sh then call chirp_wrap

Dockerfile

# Append to any Dockerfile:
RUN apk add --no-cache curl && \
    curl -fsSL https://chirpapp.dev/connectors/bash/chirp.sh \
      -o /usr/local/share/chirp.sh

# At runtime inside the container:
# . /usr/local/share/chirp.sh
# chirp_wrap @agent "container task" -- /app/run.sh

Editors & agents

One file, your coding agent knows Chirp.

Cursor

Ask Cursor to send a notification — it knows how.

A .cursorrules file teaches Cursor when and how to reach for Chirp. Pre-built, env-var referenced, safe to commit.

Livechirp login

Setup

1chirp login once on your laptop (so any CLI/SDK Cursor's agent runs auto-auths)
2From your project root: curl -o .cursorrules https://chirpapp.dev/agent-skill/cursorrules
3Commit the file. In Cursor, ask things like "send me a push when the build finishes"

shell

curl -o .cursorrules https://chirpapp.dev/agent-skill/cursorrules

# Now in Cursor: "Send me a push when the build finishes"
# and it will call Chirp without being told how.

Windsurf

Same story as Cursor — Cascade learns Chirp from one file.

.windsurfrules file. Download from the dashboard or the URL below; safe to commit.

Livechirp login

Setup

1chirp login once on your laptop
2curl -o .windsurfrules https://chirpapp.dev/agent-skill/windsurfrules
3Commit the file — Cascade picks it up automatically

shell

curl -o .windsurfrules https://chirpapp.dev/agent-skill/windsurfrules

Claude Code

Long-running Claude Code sessions — phone shows Claude is working.

SessionStart and Stop hooks fire a Live Activity while Claude is working. Drop-in Python hook script.

Livechirp login

Setup

1chirp login once so the hooks inherit your credentials
2Drop the chirp-hook.py into ~/.claude/hooks/
3Add the hooks block to ~/.claude/settings.json (see snippet)

~/.claude/settings.json

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command",
      "command": "python3 ~/.claude/hooks/chirp-hook.py SessionStart" }] }],
    "Stop":         [{ "hooks": [{ "type": "command",
      "command": "python3 ~/.claude/hooks/chirp-hook.py Stop" }] }]
  }
}

AGENTS.md

Codex CLI · Aider · Zed · any tool that reads AGENTS.md.

Portable one-file agent context that teaches the agent how to call Chirp. Drop in any repo root.

Livechirp login

Setup

1chirp login once on your laptop
2curl -o AGENTS.md https://chirpapp.dev/agent-skill/AGENTS.md
3Commit the file at your repo root

shell

curl -o AGENTS.md https://chirpapp.dev/agent-skill/AGENTS.md

Webhooks

Paste a URL into a third party. No code.

Raw HTTP

Languages without an SDK, embedded systems, one-offs.

Four endpoints — start, update, end, notify. Five lines of curl gets you a working integration.

Liveenv var

Setup

1Set CHIRP_API_KEY in env wherever your code runs
2POST JSON to /v1/activity/start, /update, /end, or /notify
3Include Authorization: Bearer $CHIRP_API_KEY header

curl

curl -X POST https://api.chirpapp.dev/v1/activity/start \
  -H "Authorization: Bearer $CHIRP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schema_id":"@agent","data":{"agentName":"job","statusMessage":"Running","state":"working"}}'

Vercel deploys

Every deploy → phone. No code, no SDK.

Paste one webhook URL into Vercel. Preview + production each get a @deploy Live Activity.

Livesigned URL

Setup

1Grab your ready-to-paste URL from chirpapp.dev/dashboard → Webhook URLs card
2Vercel → Project → Settings → Git → Deploy Hooks → Add
3Paste the URL. Vercel fires on every deploy automatically.

shell

# Your URL (from the dashboard):
https://api.chirpapp.dev/v1/webhooks/vercel?key=YOUR_KEY

GitHub webhook

Repos not using Actions, or global org-level events.

deployment_status / workflow_run / release events translate to @deploy / @build / notifications.

Livesigned URL

Setup

1Repo or org → Settings → Webhooks → Add webhook
2Payload URL: https://api.chirpapp.dev/v1/webhooks/github?key=YOUR_KEY
3Content type: application/json · Events: deployment_status, workflow_run, release

shell

# In GitHub:
Payload URL: https://api.chirpapp.dev/v1/webhooks/github?key=YOUR_KEY
Content type: application/json
Events: deployment_status, workflow_run, release (pick what you care about)

CircleCI webhook

CircleCI users who want status without touching config.yml.

Workflow completions + job completions route to @build activities and notifications automatically.

Livesigned URL

Setup

1CircleCI → Project Settings → Webhooks → Add
2Receiver URL: https://api.chirpapp.dev/v1/webhooks/circleci?key=YOUR_KEY
3Events: workflow-completed, job-completed

shell

# Your URL (from the dashboard):
https://api.chirpapp.dev/v1/webhooks/circleci?key=YOUR_KEY

Stripe

Solo founder / small team — get pinged on every sale.

Payment succeeded, subscription created, invoice failed, and friends all become push notifications.

Livesigned URL

Setup

1Stripe → Developers → Webhooks → Add endpoint
2Endpoint URL: https://api.chirpapp.dev/v1/webhooks/stripe?key=YOUR_KEY
3Events: payment_intent.succeeded, payment_intent.payment_failed, customer.subscription.created, invoice.payment_failed

shell

# In Stripe → Developers → Webhooks:
Endpoint: https://api.chirpapp.dev/v1/webhooks/stripe?key=YOUR_KEY
Events to send: payment_intent.succeeded, payment_intent.payment_failed,
                customer.subscription.created, invoice.payment_failed

Sentry

Production errors — know before your users complain.

Forward Sentry alerts as push notifications. Filter by project, environment, or issue level in Sentry itself.

Livesigned URL

Setup

1Sentry → Alerts → New Alert Rule (or edit an existing one)
2Add action: Send a notification via a webhook
3URL: https://api.chirpapp.dev/v1/webhooks/inbound?key=YOUR_KEY

shell

# Your URL (from the dashboard):
https://api.chirpapp.dev/v1/webhooks/inbound?key=YOUR_KEY

Grafana

Infra alerts — CPU, error rate, latency thresholds.

Grafana contact point → Chirp push. Title/body extraction handles Grafana's alert payload out of the box.

Livesigned URL

Setup

1Grafana → Alerting → Contact points → New contact point
2Integration: Webhook
3URL: https://api.chirpapp.dev/v1/webhooks/inbound?key=YOUR_KEY

shell

# Your URL (from the dashboard):
https://api.chirpapp.dev/v1/webhooks/inbound?key=YOUR_KEY

Any JSON webhook

Anything we haven't built a translator for — Linear, custom scripts.

Best-effort title/body extraction from common payload shapes. Append ?mode=activity&schema=@alert to fire a Live Activity instead.

Livesigned URL

Setup

1Grab your URL from chirpapp.dev/dashboard → Webhook URLs card
2Paste it into the third party's webhook config
3(Optional) Append &mode=activity&schema=@alert to fire a Live Activity instead of a push

shell

https://api.chirpapp.dev/v1/webhooks/inbound?key=YOUR_KEY
# Paste into any service's webhook field.