Quick start

Clawback is a Claude Code channel plugin. It connects to a hosted server via WebSocket and delivers events — webhooks and crons — directly into your Claude Code session.

1. Clone and install

git clone https://github.com/clawback-io/clawback.git ~/.config/claude/channels/clawback-plugin
cd ~/.config/claude/channels/clawback-plugin
bun install

2. Add the MCP server

From whichever project directory you want to use Clawback in:

# Add to current project
claude mcp add -s project clawback -- bun run \
  --cwd ~/.config/claude/channels/clawback-plugin --shell=bun --silent start

# Or add globally (all projects)
claude mcp add clawback -- bun run \
  --cwd ~/.config/claude/channels/clawback-plugin --shell=bun --silent start

3. Authenticate

Visit getclawback.io/auth/cli to log in with GitHub. You'll get a shell command to save your connection config. Paste it in your terminal.

4. Restart Claude Code

The plugin connects automatically on startup. Once connected, you manage everything through Claude in natural language.

5. Tell Claude what you want

Claude will create the source, configure event routing, and give you the webhook URL to paste into your GitHub repo's webhook settings.

Claude will set up a persistent cron job that fires into your session on schedule.

Configuration

After authenticating, your config is saved at ~/.config/claude/channels/clawback/config.json (or ~/.claude/channels/clawback/config.json depending on your system):

{
  "remote": "wss://getclawback.io/ws",
  "connectionToken": "cbt_your_token_here",
  "notifications": true
}

Environment variables

Creating sources

A webhook source is an endpoint on the Clawback server that accepts incoming webhooks from an external service. Each source has a slug (used in the URL), a verification type, and optional route mappings that tell Claude what to do with each event type.

Claude will create the source and give you a webhook URL to paste into your service's webhook settings.

Event routing

When a webhook arrives, Clawback needs to know two things: what kind of event is it, and what should Claude do with it.

Extracting the event type

Different services put the event type in different places. You tell Clawback where to look:

Mapping events to actions

Once Clawback can extract the event type, you map specific events to skills or prompts. When an event matches, that skill is prepended to the payload before delivering it to Claude.

With this setup:

• A pull_request.opened webhook arrives — Claude gets /review with the full payload
• An issues.opened webhook arrives — Claude gets /triage with the payload
• A push event arrives — silently dropped (no matching route)

You can also use * as a catch-all to handle any events that don't have a specific route.

Signature verification

Clawback supports HMAC signature verification for incoming webhooks. When creating a source, you specify the verification type:

• github — verifies the X-Hub-Signature-256 header using your webhook secret
• stripe — verifies Stripe's Stripe-Signature header
• generic — HMAC-SHA256 verification with a configurable header
• none — no signature verification (for services that don't support it)

Webhook secrets are encrypted at rest with AES-256-GCM. The plaintext secret is never stored — only the encrypted form.

Creating crons

Clawback crons are persistent scheduled jobs stored on the server. Unlike Claude Code's built-in /schedule which expires after 7 days, Clawback crons run forever until you delete them. They survive session restarts, disconnections, and machine reboots.

Tell Claude what schedule you want in natural language:

Crons use standard 5-field cron expressions under the hood (minute hour day-of-month month day-of-week), but you don't need to know the syntax — Claude will translate for you.

How crons fire

• When a cron fires, the prompt is delivered as a channel event — same as a webhook
• If you're connected, it arrives immediately. If not, it queues until you reconnect
• Claude must call event_ack after handling each cron event before the next one arrives
• Crons targeted to a session tag only fire in that session

Managing crons

Skills and prompts

The cron prompt can be anything:

• A skill — /catchup, /review-prs, /deploy-check — Claude invokes the skill directly
• Freeform text — "Check if there are any open PRs that need review" — Claude treats it as a prompt

Listing and deleting

Why use Clawback for events

Channels like Telegram deliver messages directly into Claude's context — if two arrive at once, they compete for attention and can interrupt each other mid-task. There's no ordering, no queue, and no guarantee that Claude finishes one thing before starting the next.

Clawback is different. Events go through a managed queue — one at a time, each fully processed and acknowledged before the next one starts. If events arrive while Claude is busy, they wait. If you're offline, they queue on the server until you reconnect. Nothing is lost, nothing is interrupted (unless you explicitly use interrupt priority).

This makes Clawback the right choice for anything that needs reliable, sequential processing: webhook handlers, cron jobs, automated workflows, and multi-agent coordination.

Session tags

When you run multiple Claude Code instances, you need events to go to the right one. Session tags solve this — label each instance and target sources and crons to it.

Each Claude Code instance can have a session tag, set via an environment variable. Sources and crons can target a specific session. The server only delivers events to connections that match.

Start sessions with tags

# A session for handling deploys
CLAWBACK_SESSION=deploys claude --dangerously-load-development-channels server:clawback

# A session for monitoring alerts
CLAWBACK_SESSION=oncall claude --dangerously-load-development-channels server:clawback

# Without a tag — receives only untagged events
claude --dangerously-load-development-channels server:clawback

Creating targeted sources

When you create a source or cron from a tagged session, it automatically targets that session. Tell Claude what you want:

Because you're in the deploys session, the source automatically targets deploys. Webhooks from this source will only go to this session, never your other ones.

You can also explicitly target a different session:

Routing rules

The key rule: tagged sessions only receive events with their tag, and untagged sessions only receive untagged events.

Inter-agent messaging

Sessions can send messages directly to each other — no webhook setup needed. Each session can discover other connected sessions and start a conversation.

Here's a real example. You have two tagged sessions — deploys managing releases and oncall handling alerts:

Claude in deploys discovers oncall via session_list, sends a message, and they coordinate directly:

deploys → oncall: "Hey, we're about to push v2.4.0. Any open incidents or blockers I should know about?"

oncall → deploys: "There's a memory leak in the payments service — found it an hour ago, patch is ready but not merged. Hold the deploy until I confirm the fix is in."

deploys → oncall: "Got it, holding deploy. Let me know when the fix lands and I'll include it."

Each message is delivered as an event in the receiving session. Claude processes it, decides how to respond, and sends a reply back — all without any user involvement after the initial prompt.

You can also broadcast to every connected session at once:

Messages to offline sessions are durably queued and delivered when they reconnect. Broadcasts (*) go only to currently connected sessions.

Disable inter-agent messaging per-session with "sessionMessaging": false in config.

Webhook source tools

Cron job tools

Event tools

Account & token tools

Messaging tools

Event priority

Webhook sources, crons, and session messages support a priority parameter: