clawhip

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. Community: Join the clawhip Discord at https://discord.gg/wSyUQYfhAw.

gajae-claw (clawhip) is 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.

Start with recipes

Use clawhip when you have an event, a destination, and a policy for whether the next step can happen automatically or needs a human/operator approval. These recipes use placeholder channel IDs and names; replace them with your own public-safe values.

Recipe 1: PR opened -> notify the maintainer/project channel

When GitHub reports a pull request event, route it to the project channel so the right maintainer sees it.

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

Example event shape:

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

Result: clawhip records the routed event and posts a compact PR notification to the project channel.

Recipe 2: CI failed twice -> summarize and escalate

Let routine CI status flow to the project channel, but reserve an escalation route for repeated failures. Your CI watcher or automation can emit the second-failure event after it observes two failed runs for the same PR or branch.

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

[[routes]]
event = "ci.failed-twice"
filter = { repo = "my-app" }
sink = "discord"
channel = "ESCALATION_CHANNEL_ID"
format = "alert"

Example escalation payload:

{
  "source": "ci-watcher",
  "event": "ci.failed-twice",
  "repo": "my-app",
  "branch": "feature/auth-flow",
  "summary": "CI failed twice on the same PR; test logs point at integration/auth_test.",
  "action": "summarize_and_escalate",
  "target": "ESCALATION_CHANNEL_ID"
}

Result: normal failures stay low-noise; repeated failures get a short summary in the escalation channel.

Recipe 3: cleanup, merge, or config change requested -> require operator approval

Some requests should notify an operator instead of letting an agent act immediately. Send those events to an approval channel and keep the requested action in the message body.

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

Example approval event:

{
  "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",
  "policy": "approval_required",
  "action": "notify_operator",
  "target": "APPROVAL_CHANNEL_ID"
}

Result: clawhip records the request and alerts an operator; the agent waits for explicit approval before cleanup, merge, or config-changing work.

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 the shared clawhip bridge in ~/.clawhip/hooks/native-hook.mjs
• for Codex, align with the official hook contract: use either ~/.codex/hooks.json or /.codex/hooks.json
• for Claude Code, install the provider-native hook config globally in ~/.claude/settings.json
• 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.

For tmux-backed recovery into an already-running hooked session, use:

clawhip deliver --session  --prompt "..." --max-enters 4

clawhip deliver validates repo-local prompt-submit hook setup, confirms the target pane is an active Codex/Claude (including OMC/OMX wrapper) session, then retries Enter until .clawhip/state/prompt-submit.json changes or the bounded retry limit is reached.

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:

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

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 

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

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.

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"

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

Bounded setup presets also support:

clawhip setup \
  --bot-token "discord-bot-token" \
  --default-channel "1234567890" \
  --default-format alert \
  --daemon-base-url "http://127.0.0.1:25294"

clawhip setup stays non-interactive and intentionally limited to the supported presets:

• Discord webhook quickstart route
• Discord bot token
• Default channel
• Default message format
• Daemon base URL
• Official GJC question subscription and repository-scoped route (channel, mention, fallback)

To opt into the official GJC question bridge from a repository checkout, provide a destination channel (or explicitly reuse the configured default channel):

clawhip setup \
  --question-channel "QUESTIONS_CHANNEL_ID" \
  --question-mention ""

# Equivalent fallback form when [defaults].channel is already configured.
clawhip setup --question-fallback

This setup path converges the setup-owned gjc-question websocket subscription and one workflow.question route filtered by the current repository identity. It never edits an existing workflow.gate route. Re-running setup updates those same named entries instead of duplicating them. Question setup only owns the destination channel, optional mention, and fallback-to-default choice; the subscription endpoint remains GJC_QUESTION_WS and is read only by the daemon environment.

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.

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 n