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

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.

Good to use together

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

OMX (oh-my-codex)

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"

# inspect active daemon-known watches later
clawhip tmux list

See skills/omx/ for ready-to-use scripts. Recommended default clawhip + OMX setup: install the native bridge from integrations/omx/ and forward the frozen hook envelope via clawhip omx hook when the CLI is available, with POST /api/omx/hook as the daemon fallback. Native OMC/OMX routing now prefers the normalized session.* contract; legacy agent.* wrapper emits remain supported for compatibility only.

OMC (oh-my-claudecode)

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.

Gajae operator setup → verify → fix

For OMC/OMX-integrated setups, clawhip is the source of truth for routing doctrine and troubleshooting. Keep session skills focused on launch mechanics, then use clawhip docs for the operational rails:

quick entrypoint: this README section
detailed OMX runbook: integrations/omx/README.md
native routing/reference contract: docs/native-event-contract.md

Setup

Confirm the daemon you plan to use is the one you expect:
```
clawhip --version
clawhip status
```

For OMX, install the native hook bridge into the target workspace, then validate it:

./integrations/omx/install-hook.sh /path/to/repo/.omx/hooks
omx hooks validate
omx hooks test

Add an explicit native session route. Use event = "session.*" and filter on repo_name, not repo:
```
[[routes]]
event = "session.*"
filter = { tool = "omx", repo_name = "clawhip" }
channel = "1480171113253175356"
format = "compact"
```
For OMC-native session traffic, keep the same event family and switch the tool filter to omc when needed.
Leave [defaults].channel configured only as a fallback safety net, not as your primary session-routing policy.

Verify

Trigger a real OMC/OMX session event and confirm it lands in the intended route channel.
If the event lands in the default channel instead, treat that as a route miss first.
If clawhip cron run is part of your operator flow, verify [[cron.jobs]] exists before treating the command as meaningful.

Fix

daemon version/runtime mismatch → reinstall or update clawhip, then restart the daemon so the running binary matches the hook/runtime you just installed.
hook installed but no native session delivery → verify both the hook install and a matching session.* route exist.
wrong repo filter → replace repo = "..." with repo_name = "..." for native session routes.

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
if you want clawhip cron run to do anything useful, define [[cron.jobs]] first; an empty cron section gives clawhip nothing meaningful to execute

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/

Native OMX hook-forwarding assets are bundled separately under:

integrations/omx/

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

Clawhip

Install / Use

README