clawhip

⭐ Optional support: the interactive repo-local install paths (./install.sh and clawhip install from a clone) can offer to star this repo after a successful install when gh is installed and authenticated. Skip it with --skip-star-prompt or CLAWHIP_SKIP_STAR_PROMPT=1.

clawhip is a daemon-first Discord notification router with a typed event pipeline, extracted sources, and a clean renderer/sink split.

Human install pitch:

Just tag @openclaw and say: install this https://github.com/Yeachan-Heo/clawhip

Then OpenClaw should:

clone the repo
run install.sh
read SKILL.md and attach the skill
scaffold config / presets
start the daemon
run live verification for issue / PR / git / tmux / install flows

What shipped in v0.3.0

Typed event model — incoming events are normalized and validated into typed envelopes before dispatch.
Multi-delivery router — one event can resolve to zero, one, or many deliveries instead of stopping at the first match.
Source extraction — git, GitHub, and tmux monitoring now run as explicit sources feeding the daemon queue.
Sink/render split — rendering is separated from transport; v0.3.0 ships with the Discord sink and default renderer.
Config compatibility — [providers.discord] is the preferred config surface, while legacy [discord] still loads.

See ARCHITECTURE.md for the release architecture that ships in v0.3.0.

Provider-native hooks for Codex + Claude

clawhip no longer treats provider-specific launch wrappers as the public integration surface. Codex and Claude own session launch plus hook registration; clawhip stays the routing, normalization, and delivery layer.

Shared v1 hook events:

SessionStart
PreToolUse
PostToolUse
UserPromptSubmit
Stop

Local ingress for sample payloads and manual verification:

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

Recommended installation model:

install provider-native hooks at project or global scope
keep provider config in the provider-owned config files
keep routing metadata in .clawhip/project.json
use .clawhip/hooks/ only for additive augmentation such as frontmatter or recent context

clawhip still pairs well with tmux when you want keyword/stale monitoring, but tmux is now optional and no longer the primary hook-registration surface.

Recipes

Dev-channel follow-up cron for Clawdbot

One practical pattern is:

system cron -> clawhip send -> Discord dev channel -> Clawdbot follows up on open PRs/issues

This works well when you want a lightweight scheduler that nudges your dev channels every 30 minutes without keeping a gateway/LLM session open just for reminders.

Example follow-up script:

#!/usr/bin/env bash
set -euo pipefail

# dev-followup.sh
# Send a periodic follow-up to active dev channels.

CHANNELS=(
  "1480171113253175356|clawhip"
  "1480171113253175357|gaebal-gajae-api"
  "1480171113253175358|worker-ops"
)

MENTION="<@1465264645320474637>"

for entry in "${CHANNELS[@]}"; do
  IFS='|' read -r channel_id project_name <<< "$entry"

  clawhip send \
    --channel "$channel_id" \
    --message "🔄 **[$project_name] Dev follow-up** $MENTION — check open PRs/issues, review open blockers, merge anything ready, and continue any stalled work."
done

You can also send one-off nudges manually:

clawhip send \
  --channel 1480171113253175356 \
  --message "🔄 **[clawhip] Dev follow-up** <@1465264645320474637> — check open PRs/issues, review blockers, and continue anything stalled."

clawhip send \
  --channel 1480171113253175357 \
  --message "🔄 **[gaebal-gajae-api] PR sweep** <@1465264645320474637> — review open PRs, merge anything ready, and post blockers on anything stuck."

Example system cron config:

SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin

*/30 * * * * bellman /home/bellman/bin/dev-followup.sh >> /tmp/dev-followup.log 2>&1

Operational notes:

keep one channel entry per active repo/project
mention your Clawdbot/OpenClaw bot user so the bot actually wakes up and acts
use plain operational language like "check open PRs/issues", "review blockers", and "continue stalled work"
this keeps scheduling outside the agent loop: cron handles timing, clawhip handles delivery, Discord handles the handoff

Filesystem-offloaded memory pattern

clawhip now documents a Claw OS-style memory pattern where MEMORY.md is the hot pointer/index layer and detailed memory lives in structured filesystem shards under memory/.

Use this when you want:

a small, fast memory surface for agents
durable project/channel/daily memory in files
explicit read/write routing instead of one giant note
ongoing memory refactoring as part of operations

Start here:

Runtime support now includes a small bootstrap/inspection surface:

# create a scaffold in the current repo
clawhip memory init --project clawhip --channel discord-alerts --agent codex

# inspect whether the expected files and directories exist
clawhip memory status --project clawhip --channel discord-alerts --agent codex

clawhip memory init creates MEMORY.md, memory/README.md, a daily shard, a project shard, topic files, and optional channel/agent shards without overwriting existing files unless you pass --force.

Plugin architecture

clawhip now includes a simple plugins/ directory for tool-specific shell bridges. Each plugin lives in its own subdirectory with:

plugin.toml for lightweight metadata
bridge.sh for shell hook entrypoints

Built-in starter plugins:

plugins/codex/
plugins/claude-code/

List installed plugins with:

clawhip plugin list

Description

Operational spec for OpenClaw / Clawdbot agents consuming this repo.

Repo role:

executable/runtime repo
daemon-first Discord notification gateway
typed event routing runtime
extracted Git/GitHub/tmux source monitors
multi-delivery router with renderer/sink separation
lifecycle surface: install / update / uninstall / start / status

Attachment model:

repo = runtime
SKILL.md = attach/install/usage instructions for OpenClaw / Clawdbot
README = agent-facing operational spec

Default daemon endpoint:

http://127.0.0.1:25294

OpenClaw install contract

Primary install entrypoint:

@openclaw install <repo_url>

Expected downstream automation behavior:

clone repo
run ./install.sh
read SKILL.md
attach skill
scaffold config / presets
start daemon
run live verification

Reference repo URL:

https://github.com/Yeachan-Heo/clawhip

Discord bot setup

Recommended: Create a dedicated Discord bot for clawhip. Do not reuse your Clawdbot / OpenClaw bot token.

clawhip sends high-volume notifications (commits, PRs, tmux keyword alerts, stale warnings). Using a separate bot keeps these cleanly separated from your AI chat bot.

Create a new bot at Discord Developer Portal (e.g. "CCNotifier")
Copy the bot token
Invite to your server with Send Messages permission
Set the token in config:

[providers.discord]
token = "your-dedicated-clawhip-bot-token"
default_channel = "your-default-channel-id"

[dispatch]
routine_batch_window_secs = 5
ci_batch_window_secs = 300

Legacy [discord] config is still accepted and normalized at load time.

[dispatch].routine_batch_window_secs controls the default Discord-only routine burst batch window. Leave it unset to keep the 5-second default, or set it to 0 to disable routine batching entirely. In v1, grouped routine bursts suppress route/event mentions for 2+ items, while explicit failure/stale/CI paths still bypass the routine batcher.

[dispatch].ci_batch_window_secs controls how long clawhip waits before flushing a GitHub CI batch summary. Leave it unset to keep the 30-second default, or increase it for longer workflows that finish jobs over several minutes.

Discord webhook setup

Webhook mode works without a bot token.

Quick start:

clawhip setup --webhook "https://discord.com/api/webhooks/..."

Route example:

[[routes]]
event = "tmux.keyword"
sink = "discord"
webhook = "https://discord.com/api/webhooks/..."

Slack webhook setup

Slack webhook routes work without a bot token.

In Slack, open the app settings for your workspace and enable Incoming Webhooks
Add a new webhook to the channel you want clawhip to notify
Copy the generated https://hooks.slack.com/services/... URL into a route

Route examples:

[[routes]]
event = "git.commit"
filter = { repo = "my-app" }
slack_webhook = "https://hooks.slack.com/services/T.../B.../xxx"
format = "compact"

[[routes]]
event = "tmux.keyword"
sink = "slack"
webhook = "https://hooks.slack.com/services/T.../B.../yyy"
format = "alert"

System model

[CLI / webhook / git / GitHub / tmux]
              -> [sources]
              -> [mpsc queue]
              -> [dispatcher]
              -> [router -> renderer -> Discord/Slack sink]
              -> [Discord REST / Slack webhook delivery]

Input sources in v0.3.0:

CLI thin clients and custom events
GitHub webhook ingress plus GitHub polling source
git monitor source
tmux monitor source
clawhip tmux new / clawhip tmux watch registration path

Input -> behavior -> verification

1. Custom client event

Input:

clawhip send --channel <id> --message "text"

Behavior:

POST to daemon /api/event
daemon routes event
Discord message emitted

Verification:

clawhip status
inspect configured Discord channel for rendered payload

2. GitHub issue preset family

Input:

GitHub webhook issues.opened
built-in GitHub issue monitor detection
CLI thin client clawhip github issue-opened ...

Behavior:

emit github.issue-opened
route via github.*
apply repo filter
prepend route mention if configured
send to Discord

Verification:

create real issue
confirm final Discord body contains:
- repo
- issue number
- title
- mention when configured

3. GitHub issue commented preset

Input:

GitHub webhook issue_comment.created
built-in GitHub issue monitor comment delta

Behavior:

emit github.issue-commented
route via github.*
apply repo filter
prepend route mention if configured

Verification:

add real issue comment
confirm final Discord message body in target channel

4. GitHub issue closed preset

Input:

GitHub webhook issues.closed
built-in GitHub issue monitor state transition

Behavior:

emit github.issue-closed
route via github.*
apply repo filter
prepend route mention if configured

Verification:

close real issue
confirm final Discord message body in target channel

5. GitHub PR preset family

Input:

GitHub webhook pull_request.*
built-in PR monitor state changes
CLI thin client clawhip github pr-status-changed ...

Behavior:

emit github.pr-status-changed
route via github.*
apply repo filter
prepend route mention if configured

Verification:

open real PR
merge / close PR
confirm final Discord message body in target channel

6. Git commit preset family

Input:

built-in git monitor polling local repo
CLI thin client clawhip git commit ...

Behavior:

emit git.commit
route through git/github family matching
preserve repo-based route filtering
prepend route mention if configured

Verification:

create real empty commit in monitored repo
confirm final Discord body contains commit summary and mention

7. Provider-native session contract

Canonical native routing now starts from provider-native Codex and Claude hook payloads and enters clawhip through clawhip native hook.

Shared v1 hook events:

SessionStart
PreToolUse
PostToolUse
UserPromptSubmit
Stop

Stable routing metadata (when available):

provider
event
session_id
directory
worktree_path
repo_name
project
branch
tool_name
command
summary
event_timestamp

Augmentation rules:

provider input + clawhip project metadata define the immutable base contract
.clawhip/hooks/ scripts may only add fields or enrich message/context
augmenters must not remove or overwrite base routing keys

Route guidance:

prefer filters like provider, event, repo_name, project, and branch
avoid route logic that depends on rendered message text
keep provider-specific extras out of the shared v1 route surface until explicitly adopted

See docs/native-event-contract.md for the routing/augmentation guide and docs/event-contract-v1.md for the frozen shared-event reference.

8. Agent lifecycle preset family

Input:

clawhip agent started --name worker-1 --session sess-123 --project my-repo
clawhip agent blocked --name worker-1 --summary "waiting for review"
clawhip agent finished --name worker-1 --elapsed 300 --summary "PR created"
clawhip agent failed --name worker-1 --error "build failed"

Behavior:

emit agent.started, agent.blocked, agent.finished, or agent.failed
route via agent.*
apply optional project/session filters
include status / elapsed / summary / error details in rendered messages
prepend route mention if configured

Verification:

send each CLI event against a running daemon
confirm final Discord body contains agent name and lifecycle state
confirm agent.* route rules match each event type

9. tmux keyword preset

Input:

built-in tmux monitor detects configured keyword
CLI thin client clawhip tmux keyword ...

Behavior:

emit tmux.keyword
route via tmux.*
prepend route mention if configured

Verification:

print configured keyword in real monitored tmux session
confirm final Discord body in target channel

10. tmux stale preset

Input:

built-in tmux stale detection
CLI thin client clawhip tmux stale ...

Behavior:

emit tmux.stale
route via tmux.*
prepend route mention if configured

Verification:

let real tmux session idle past threshold
confirm final Discord body in target channel

11. Provider-native sessions + tmux fallback

Preferred input:

clawhip native hook --provider codex --file payload.json
clawhip native hook --provider claude --file payload.json
clawhip tmux list

Fallback/debug input:

clawhip tmux new -s <session> \
  --mention '<@id>' \
  --keywords 'error,PR created,FAILED,complete' \
  --stale-minutes 10 \
  --format alert \
  --retry-enter true \
  --retry-enter-count 4 \
  --retry-enter-delay-ms 250 \
  --shell /bin/zsh \
  -- command args

clawhip tmux watch -s <existing-session> \
  --mention '<@id>' \
  --keywords 'error,PR created,FAILED,complete' \
  --stale-minutes 10 \
  --format alert \
  --retry-enter true

Behavior:

Codex and Claude should own session launch and hook registration
clawhip native hook is the local thin-client ingress for provider payloads
tmux new / tmux watch are fallback paths for debugging or manual recovery
tmux list shows active daemon-known watches with source, registration timestamp, and parent-process info
final delivery still goes through daemon routing

Routing note:

session names are labels for operators, not routing authority
project metadata should be the source of truth for routing
broad prefix monitors like clawhip* are dangerous because they can overlap with launcher-registered watches and create stale/keyword noise

Verification:

launch a real Codex or Claude session with provider-native hooks enabled
verify the tmux pane is actually alive
confirm routed delivery in Discord
if alert text conflicts with pane reality, trust the pane and inspect monitor registrations

12. install lifecycle preset

Input:

./install.sh
clawhip install
clawhip update --restart
clawhip uninstall --remove-systemd --remove-config

Behavior:

install binary from git clone
ensure config dir exists
optional systemd install
optional post-install GitHub star prompt on interactive local installs
update rebuilds/reinstalls and optionally restarts daemon
uninstall removes runtime artifacts

Verification:

clawhip --help
clawhip status
systemctl status clawhip when systemd-enabled

Preset event families

GitHub family

github.issue-opened
github.issue-commented
github.issue-closed
github.pr-status-changed

Git family

git.commit
git.branch-changed

Agent family

agent.started
agent.blocked
agent.finished
agent.failed

Native session family

session.started
session.blocked
session.finished
session.failed
session.retry-needed
session.pr-created
session.test-started
session.test-finished
session.test-failed
session.handoff-needed

tmux family

tmux.keyword
tmux.stale

Route contract

Config file:

~/.clawhip/config.toml

Route model:

[[routes]]
event = "github.*"
filter = { repo = "clawhip" }
sink = "discord"
channel = "1480171113253175356"
mention = "<@1465264645320474637>"
format = "compact"
allow_dynamic_tokens = false

[[routes]]
event = "session.*"
filter = { tool = "omx", repo_name = "clawhip" }
sink = "discord"
channel = "1480171113253175356"
format = "compact"
allow_dynamic_tokens = false

[[routes]]
event = "agent.*"
filter = { project = "clawhip" }
sink = "discord"
channel = "1480171113253175356"
format = "alert"
allow_dynamic_tokens = false

Resolution rules:

event family match
payload filter match
route sink / target / format / template / mention applied
default fallback used if route fields absent

Dynamic token contract

Only for routes with:

allow_dynamic_tokens = true

Supported tokens:

{repo}
{number}
{title}
{session}
{keyword}
{sh:...}
{tmux_tail:session:lines}
{file_tail:/path:lines}
{env:NAME}
{now}
{iso_time}

Safety:

allowlisted token kinds only
route-level opt-in only
short timeout
output cap

Install surface

From crates.io

cargo install clawhip

Published at crates.io/crates/clawhip. Requires Rust toolchain.

Prebuilt binary installer (recommended, no Rust needed)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Yeachan-Heo/clawhip/releases/latest/download/clawhip-installer.sh | sh

This installs the latest prebuilt clawhip binary from GitHub Releases into $CARGO_HOME/bin (typically ~/.cargo/bin).

Release artifacts are generated for these Rust target triples: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, and aarch64-apple-darwin.

Repo-local install

./install.sh
./install.sh --systemd

install.sh now tries the latest prebuilt release first and falls back to cargo install --path . --force when a matching release asset is unavailable. If Cargo is needed for the fallback path but not installed, the script prints Rustup setup instructions. When --systemd is used, the installed binary is also copied to /usr/local/bin/clawhip so the bundled service unit can start it.

In interactive terminals, both the repo-local installer and clawhip install may offer an optional post-install GitHub star prompt via authenticated gh api access. It never runs automatically, is skipped when gh is missing or unauthenticated, and can be disabled with ./install.sh --skip-star-prompt, clawhip install --skip-star-prompt, or CLAWHIP_SKIP_STAR_PROMPT=1.

Runtime lifecycle commands

clawhip install
clawhip install --systemd
clawhip install --skip-star-prompt
clawhip update --restart
clawhip uninstall
clawhip uninstall --remove-systemd --remove-config

clawhip install now matches the repo-local installer's optional GitHub star prompt behavior: it only appears in interactive terminals, is skipped when gh is missing or unauthenticated, never stars automatically, and can be disabled with clawhip install --skip-star-prompt or CLAWHIP_SKIP_STAR_PROMPT=1 clawhip install.

systemd contract

Unit file:

deploy/clawhip.service

Expected install path:

copy to /etc/systemd/system/clawhip.service
systemctl daemon-reload
systemctl enable --now clawhip

Live verification runbook

Use:

docs/live-verification.md
scripts/live-verify-default-presets.sh

Required live sign-off presets:

issue opened
issue commented
issue closed
PR opened
PR status changed
PR merged
git commit
provider-native shared hook events
tmux keyword
tmux stale
tmux wrapper
tmux watch
install/update/uninstall

Minimal operational commands

clawhip                 # start daemon
clawhip status          # daemon health
clawhip config          # config management
clawhip send ...        # thin client custom event
clawhip github ...      # thin client GitHub event
clawhip git ...         # thin client git event
clawhip agent ...       # thin client agent lifecycle event
clawhip native hook ... # provider-native hook thin client
clawhip tmux ...        # thin client / wrapper surface
clawhip plugin list     # list installed/bundled shell-hook plugins

Name		Name	Last commit message	Last commit date
Latest commit History 208 Commits
.github/workflows		.github/workflows
assets		assets
deploy		deploy
docs		docs
integrations		integrations
plugins		plugins
scripts		scripts
skills		skills
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md
dist-workspace.toml		dist-workspace.toml
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

clawhip

What shipped in v0.3.0

Provider-native hooks for Codex + Claude

Recipes

Dev-channel follow-up cron for Clawdbot

Filesystem-offloaded memory pattern

Plugin architecture

Description

OpenClaw install contract

Discord bot setup

Discord webhook setup

Slack webhook setup

System model

Input -> behavior -> verification

1. Custom client event

2. GitHub issue preset family

3. GitHub issue commented preset

4. GitHub issue closed preset

5. GitHub PR preset family

6. Git commit preset family

7. Provider-native session contract

8. Agent lifecycle preset family

9. tmux keyword preset

10. tmux stale preset

11. Provider-native sessions + tmux fallback

12. install lifecycle preset

Preset event families

GitHub family

Git family

Agent family

Native session family

tmux family

Route contract

Dynamic token contract

Install surface

From crates.io

Prebuilt binary installer (recommended, no Rust needed)

Repo-local install

Runtime lifecycle commands

systemd contract

Live verification runbook

Minimal operational commands

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 16

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages