clawhip: routing agent and CI events to Discord channels

Events in, messages out, no gateway session

clawhip is described in the repository description as an event-to-channel notification router that bypasses gateway sessions to avoid context pollution, and the README calls it the control plane for agents: route events from GitHub, Discord, tmux and other tools to the right human or agent, record what happened, and separate automatic actions from approval-required actions.

The bypass is the design decision that defines the project. A conventional Discord bot joins a gateway, receives every event on the server, and holds them in a session with a conversation history. For an agent runtime that is the wrong shape, because every message the bot sees becomes context the agent has to carry. clawhip instead binds to live native GJC SDK sessions, routes authoritative lifecycle, question, gate and failure events through a normal ledger, router and sink pipeline, and preserves loopback-only credentials and public-safe projections. The README is explicit about ownership: GJC remains the process owner, and clawhip observes and controls only through the SDK contract.

So the unit of work is an event, not a conversation. The audience is small teams whose agents act in GitHub and terminal sessions and who need the humans to see the right things without the bot swallowing the channel.

Typed envelopes and a router that does not stop at the first match

The v0.3.0 release notes describe the architecture that the current code is built on, and four points in them describe the mechanism.

The typed event model normalises and validates incoming events into typed envelopes before dispatch, so a malformed payload is rejected at the boundary rather than half-processed by a sink. The multi-delivery router resolves one event to zero, one or many deliveries instead of stopping at the first match, which is what makes policy expressible as configuration: the same event can notify one channel and escalate to another.

Source extraction moved git, GitHub and tmux monitoring into explicit sources feeding the daemon queue, rather than having them trigger the router indirectly. And the sink and render split separates rendering from transport, so a message can be formatted once and delivered over more than one transport, with v0.3.0 shipping the Discord sink and a default renderer.

One more piece of configuration history matters for upgrades. The preferred config surface is now [providers.discord], while the legacy [discord] section still loads. That back-compatibility is deliberate and is what lets an existing config survive an upgrade rather than failing at startup.

Routes are TOML, and the event name is the match

Configuration lives at ~/.clawhip/config.toml and consists of route tables. The first recipe in the documentation routes a pull request event to a project channel:

# ~/.clawhip/config.toml
[[routes]]
event = "github.pr-status-changed"
filter = { repo = "my-app" }
sink = "discord"
channel = "PROJECT_CHANNEL_ID"
format = "compact"

Four fields do the work. The event key is the event name to match, the filter narrows by attributes such as repo, the sink names the transport and the channel names the destination, and the format selects how the message is rendered. The rendered result is a compact notification rather than a raw payload dump.

The event shape the router expects is a JSON object with a source, an event, the attributes used by the filter, and an action and target:

{
  "source": "github",
  "event": "pull_request.opened",
  "repo": "my-app",
  "pr": 42,
  "action": "notify",
  "target": "PROJECT_CHANNEL_ID"
}

Note that the event name in the payload, pull_request.opened, differs from the name in the route, github.pr-status-changed. That is a real trap for anyone configuring this from scratch: the route key and the payload event are separate namespaces, and a mismatch produces no delivery at all rather than an error. The second recipe makes the same point with ci.failed-twice, an event the CI watcher is expected to emit itself after observing two failed runs for the same pull request or branch. The routing table covers both the source event and the derived one, so routine failures stay in the project channel while repeated failures get a summary in an escalation channel with format = "alert".

Approval routes keep destructive work with a human

The third recipe is the one that makes this a control plane rather than a notification bot. Some events should reach a person instead of triggering an agent action:

# ~/.clawhip/config.toml
[[routes]]
event = "agent.approval-requested"
filter = { repo = "my-app" }
sink = "discord"
channel = "APPROVAL_CHANNEL_ID"
format = "alert"

The payload carries the request and the reason, and it names the policy explicitly:

{
  "source": "agent",
  "event": "agent.approval-requested",
  "repo": "my-app",
  "request": "merge PR #42 after checks pass",
  "reason": "merge changes the shared branch and should be operator-approved",
  "action": "notify_operator",
  "target": "APPROVAL_CHANNEL_ID"
}

What comes out of that is a recorded request and an operator alert, with the agent waiting for explicit approval before doing cleanup, merge or config-changing work.

Encoding this as a route rather than as a line in an agent prompt is the substantive idea. A prompt instruction can be overridden by a later instruction or lost in a long context window. A route is a configuration entry that the router evaluates on every event, so the policy applies to the class of action rather than to one conversation, and the request itself is written to the ledger on its way to the channel, which gives you the audit trail afterwards.

Providers own session launch, clawhip owns routing

The integration direction changed in a later release, and the current model is worth understanding before you wire anything up.

clawhip no longer treats provider-specific launch wrappers as the public integration surface. Codex and Claude own session launch plus hook registration, and clawhip stays the routing, normalization and delivery layer. Five shared version 1 hook events are supported: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit and Stop.

For local testing there is a native hook ingress that accepts a payload file or standard input:

clawhip native hook --provider codex --file payload.json
clawhip native hook --provider claude --file payload.json
cat payload.json | clawhip native hook --provider codex

The recommended installation model puts the shared bridge in ~/.clawhip/hooks/native-hook.mjs, points Codex at ~/.codex/hooks.json or a repository level .codex/hooks.json, installs the provider-native hook configuration for Claude Code in ~/.claude/settings.json, keeps routing metadata in .clawhip/project.json, and reserves .clawhip/hooks/ for additive augmentation such as frontmatter or recent context. Provider configuration stays in the provider's own files, which is what makes the setup survive an agent tool upgrade.

tmux is still supported for keyword and stale monitoring, but the documentation states it is now optional and no longer the primary hook-registration surface. For recovering into a session that is already running and already hooked, there is a deliver command that validates the repo-local prompt-submit hook setup, confirms the target pane is an active Codex or Claude session including OMC and OMX wrappers, and retries Enter until the state file changes or the bounded retry limit is reached:

clawhip deliver --session <tmux-session> --prompt "..." --max-enters 4

Installing, and one behaviour to know about

clawhip is published on crates.io and the repository ships an install script, so there are two routes. The README describes the interactive repo-local paths, ./install.sh and clawhip install from a clone, and the documented sequence for an agent-driven install is to clone the repo, run install.sh, read SKILL.md and attach the skill, scaffold config and presets, start the daemon, and run live verification for issue, pull request, git, tmux and install flows.

There is one behaviour in that install path worth knowing before you run it on a shared or monitored machine. The install can offer to star the repository after a successful install, when the gh command is installed and authenticated. The documentation gives the way to suppress it, with the --skip-star-prompt flag or the CLAWHIP_SKIP_STAR_PROMPT=1 environment variable. That is a network call to GitHub triggered by an installer, which is exactly the kind of thing an organisation with egress policy or an audit requirement will want to know about in advance rather than discover in a log.

The repository layout is consistent with a project that has grown. Alongside src/, tests/ and Cargo.toml there are ARCHITECTURE.md, AGENTS.md, SKILL.md and CHANGELOG.md, plus directories for integrations/, plugins/, skills/, scripts/, deploy/, artifacts/, docs/ and geobench/, and a dist-workspace.toml for the distribution build.

Rust dependencies, release pace and the licence

Cargo.toml describes the crate as clawhip version 0.6.17, edition 2024, licensed MIT, categorised as a command line utility and a development tool, with keywords for discord, notifications, tmux, github and devops. The dependency list is short and tells you the shape of the thing: axum 0.8 for the HTTP surface, clap 4.5 with derive and env features for the command line, reqwest 0.12 with rustls-tls and no default features, tokio-tungstenite for websockets, tokio with the full feature set, serde and toml for configuration, and ring plus sha2 for cryptographic operations. libc is scoped to unix targets, and fs2 is there for file locking. The dev dependencies are serial_test and tempfile, with the websocket feature of axum enabled only for a deterministic fake SDK endpoint fixture, since production serves plain HTTP and JSON.

That last detail is worth flagging. The dev-dependency comment says the fake SDK endpoint fixture upgrades websockets for tests while production serves plain HTTP and JSON, which tells you the native session binding path is exercised in tests through a fake endpoint rather than against a live GJC SDK.

The release picture is fast and young. v0.6.15, v0.6.16 and v0.6.17 were all published on 2026-10-16, the same day as the last push, and the crate version in Cargo.toml matches the newest tag. A 0.x version with three patch releases in one day means the interfaces are still moving and the changelog, not the version number, is the record of what changed. MIT licensing keeps the reuse terms simple, with attribution as the only obligation.

Editorial conclusion

Adopt clawhip when you want a single, auditable path from tool events to a human channel, with the policy decision of automatic versus approval-required encoded in routes rather than in agent prompts. Skip it if you need a general Discord bot with a command interface, or if you are not prepared to own a 0.x version whose interfaces are still moving, since releases v0.6.15 to v0.6.17 all landed on 2026-10-16. Verify first that your event source emits the event names your config filters on, because the router matches on the event string and a mismatch is silently unrouted.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Yeachan-Heo/clawhip on GitHub