⭐ 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

• Install lifecycle polish — repo-local installs, clawhip install, clawhip update, and clawhip uninstall are documented and aligned for clone-local operator workflows.
• Optional GitHub support prompt — interactive install flows can offer an explicit opt-in GitHub star prompt, with --skip-star-prompt and CLAWHIP_SKIP_STAR_PROMPT=1 available on both installer surfaces.
• Filesystem memory scaffolds — clawhip memory init and clawhip memory status bootstrap and inspect the filesystem-offloaded memory layout for repos and workspaces.
• Native session contract polish — OMC/OMX payload normalization now prefers the lower-noise session.* route family while keeping legacy agent.* compatibility.
• Config compatibility — [providers.discord] remains the preferred config surface, while legacy [discord] still loads.

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

clawhip pairs well with coding session tools that run in tmux:

OpenAI Codex wrapper with auto-monitoring. Launch monitored coding sessions:

clawhip tmux new -s issue-123 \
  --channel YOUR_CHANNEL_ID \
  --mention "<@your-user-id>" \
  --keywords "error,PR created,complete" \
  -- 'source ~/.zshrc && omx --madmax'

# or attach monitoring to an existing tmux session
clawhip tmux watch -s issue-123 \
  --channel YOUR_CHANNEL_ID \
  --mention "<@your-user-id>" \
  --keywords "error,PR created,complete"

See skills/omx/ for ready-to-use scripts. Native OMC/OMX routing now prefers the normalized session.* contract; legacy agent.* wrapper emits remain supported for compatibility.

Claude Code wrapper with auto-monitoring. Launch monitored coding sessions:

clawhip tmux new -s issue-456 \
  --channel YOUR_CHANNEL_ID \
  --mention "<@your-user-id>" \
  --keywords "error,PR created,complete" \
  -- 'source ~/.zshrc && omc --openclaw --madmax'

See skills/omc/ for ready-to-use scripts. Direct Slack/Discord notifications inside OMC/OMX should be treated as deprecated; emit native events and let clawhip own routing, mention policy, and formatting.

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

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:

• docs/memory-offload-architecture.md
• docs/memory-offload-guide.md
• docs/examples/MEMORY.example.md
• skills/memory-offload/SKILL.md

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.

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

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

Primary install entrypoint:

@openclaw install <repo_url>

Expected downstream automation behavior:

1. clone repo
2. run ./install.sh
3. read SKILL.md
4. attach skill
5. scaffold config / presets
6. start daemon
7. run live verification

Reference repo URL:

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

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.

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

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

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

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 routes work without a bot token.

1. In Slack, open the app settings for your workspace and enable Incoming Webhooks
2. Add a new webhook to the channel you want clawhip to notify
3. 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"

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

Input sources in v0.4.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:

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

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

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

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

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

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

Canonical native routing for OMC/OMX uses session.* events after clawhip normalization.

Accepted upstream inputs:

• legacy wrapper emits like agent.started / agent.finished / agent.failed
• OMC command/HTTP payloads with signal.routeKey
• OMX hook payloads with context.normalized_event

Canonical normalized events:

• 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

Normalized metadata (when upstream provides it):

• tool
• session_name
• session_id
• repo_name
• repo_path
• worktree_path
• branch
• issue_number
• pr_number
• pr_url
• command
• tool_name
• test_runner
• summary
• error_message
• event_timestamp

Route guidance:

• prefer session.* for new native OMC/OMX routes
• agent.* remains supported for clawhip-local wrapper compatibility
• agent.started|blocked|finished|failed and session.started|blocked|finished|failed cross-match in routing for backward compatibility
• prefer route filters like tool, repo_name, session_name, issue_number, and branch over brittle message parsing

See docs/native-event-contract.md for the full normalization/deprecation notes.

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

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

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

Input:

clawhip tmux new -s <session> \
  --channel <id> \
  --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> \
  --channel <id> \
  --mention '<@id>' \
  --keywords 'error,PR created,FAILED,complete' \
  --stale-minutes 10 \
  --format alert \
  --retry-enter true

Behavior:

• tmux new creates a tmux session using the user's default shell (or --shell override)
• tmux new sends the requested command into the session, retrying Enter for TUI apps by default with exponential backoff (--retry-enter=false disables it, --retry-enter-count / --retry-enter-delay-ms tune retries)
• tmux watch attaches monitoring to an already-running tmux session
• both commands register the session with the daemon
• daemon monitors keyword/stale events
• final delivery goes through daemon routing

Verification:

• run wrapper or watch an existing session
• emit keyword in pane
• confirm Discord message body and mention

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

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

• git.commit
• git.branch-changed

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

• 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.keyword
• tmux.stale

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:

1. event family match
2. payload filter match
3. route sink / target / format / template / mention applied
4. default fallback used if route fields absent

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

cargo install clawhip

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

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, aarch64-apple-darwin, and x86_64-pc-windows-msvc.

./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.

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.

Unit file:

deploy/clawhip.service

Expected install path:

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

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
• agent started / blocked / finished / failed
• tmux keyword
• tmux stale
• tmux wrapper
• tmux watch
• install/update/uninstall

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 tmux ...        # thin client / wrapper surface
clawhip plugin list     # list installed/bundled shell-hook plugins