clawhip
Attach/install/use clawhip as a daemon-first notification gateway runtime for OpenClaw / Clawdbot
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/yeachan-heo--clawhip)HTML
<a href="/listings/yeachan-heo--clawhip"><img src="/api/listings/yeachan-heo--clawhip/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 174 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: clawhip
- description: Attach/install/use clawhip as a daemon-first notification gateway runtime for OpenClaw / Clawdbot
- ---
- # clawhip skill attachment surface
- ## Intent
- Use this repo as:
- - executable/runtime repo
- - daemon process for Discord notification routing
- - attachable skill surface for OpenClaw / Clawdbot
- ## Prerequisites
- ⭐ If you want to support clawhip, star this repository. The interactive repo-local installer and `clawhip install` can offer an optional post-install GitHub star prompt via authenticated `gh api` access when `gh` is installed and authenticated. Skip it with `--skip-star-prompt` or `CLAWHIP_SKIP_STAR_PROMPT=1`.
- ```bash
- gh api --method PUT /user/starred/Yeachan-Heo/clawhip --silent
- ```
- ## Primary install flow
- Preferred operator instruction:
- ```text
- @openclaw install https://github.com/Yeachan-Heo/clawhip
- ```
- Expected automation flow:
- 1. clone repo
- 2. run `./install.sh`
- 3. read this `SKILL.md`
- 4. attach skill
- 5. scaffold `~/.clawhip/config.toml`
- 6. start daemon
- 7. run live verification presets
- ## Runtime surface
- Default daemon URL:
- ```text
- http://127.0.0.1:25294
- ```
- Core commands:
- ```bash
- clawhip
- clawhip start
- clawhip status
- clawhip config
- clawhip send --channel <id> --message "..."
- clawhip github issue-opened ...
- clawhip github pr-status-changed ...
- clawhip git commit ...
- clawhip tmux keyword ...
- clawhip tmux stale ...
- clawhip tmux new -s <session> --channel <id> --keywords error,complete --shell /bin/zsh -- command
- clawhip tmux watch -s <existing-session> --channel <id> --mention '<@id>' --keywords error,complete
- ```
- ## Lifecycle surface
- ```bash
- clawhip install
- clawhip install --systemd
- clawhip install --skip-star-prompt
- clawhip update --restart
- clawhip uninstall --remove-systemd --remove-config
- ./install.sh
- ./install.sh --systemd
- ./install.sh --skip-star-prompt
- ```
- ## Discord bot token (recommended setup)
- ⚠️ **Create a dedicated Discord bot for clawhip notifications.** Do not reuse your Clawdbot / OpenClaw bot token.
- Why:
- - clawhip sends high-volume notifications (commits, PRs, tmux events)
- - Using the same bot token as your gateway pollutes the bot's identity
- - A separate bot (e.g. "CCNotifier") keeps notifications cleanly separated from AI chat
- - If clawhip restarts or crashes, it won't affect your main bot
- Setup:
- 1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
- 2. Create a new application (e.g. "clawhip-notifier" or "CCNotifier")
- 3. Create a bot, copy the token
- 4. Invite the bot to your server with Send Messages permission
- 5. Use this token in `~/.clawhip/config.toml`:
- ```toml
- [discord]
- token = "your-dedicated-clawhip-bot-token"
- ```
- ## Config scaffold expectations
- Key sections:
- - `[discord]`
- - `[daemon]`
- - `[defaults]`
- - `[[routes]]`
- - `[monitors]`
- - `[[monitors.git.repos]]`
- - `[[monitors.tmux.sessions]]`
- Typical preset route:
- ```toml
- [[routes]]
- event = "github.*"
- filter = { repo = "clawhip" }
- channel = "1480171113253175356"
- mention = "<@1465264645320474637>"
- format = "compact"
- ```
- ## Dynamic template opt-in
- ```toml
- [[routes]]
- event = "tmux.*"
- allow_dynamic_tokens = true
- template = "{session}\n{tmux_tail:issue-1456:20}\n{iso_time}"
- ```
- Allowed dynamic tokens:
- - `{sh:...}`
- - `{tmux_tail:session:lines}`
- - `{file_tail:/path:lines}`
- - `{env:NAME}`
- - `{now}`
- - `{iso_time}`
- ## Filesystem-offloaded memory pattern
- When using clawhip as part of a broader Claw OS workflow, treat memory as an offloaded filesystem tree:
- - `MEMORY.md` = small pointer/index/current-beliefs layer
- - `memory/` = detailed project/channel/daily/handoff memory
- - update root memory only when the map or current summary changes
- Read before adopting this pattern:
- - `docs/memory-offload-architecture.md`
- - `docs/memory-offload-guide.md`
- - `docs/examples/MEMORY.example.md`
- - `skills/memory-offload/SKILL.md`
- ## Verification surface
- Use the live operational runbook:
- - `docs/live-verification.md`
- - `scripts/live-verify-default-presets.sh`
- Preset verification targets:
- - GitHub issue opened / commented / closed
- - GitHub PR opened / status changed / merged
- - git commit monitor
- - tmux keyword / stale / wrapper / watch
- - install / update / uninstall
- ## Attachment summary
- ```text
- repo = runtime
- SKILL.md = attach/install/usage contract
- README.md = operational spec for agents
- ```
README.md · README · 1,535 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # clawhip
- Clawhip is a GJC-first event router. It automatically discovers and binds live
- native GJC SDK sessions, routes authoritative lifecycle, question, gate, and
- failure events through the normal ledger/router/sink pipeline, and preserves
- loopback-only credentials and public-safe projections. GJC remains the process
- owner; Clawhip observes and controls only through the SDK contract.
- <p align="center">
- <img src="assets/clawhip-mascot.jpg" width="400" alt="clawhip mascot" />
- </p>
- <p align="center">
- <a href="https://crates.io/crates/clawhip"><img src="https://img.shields.io/crates/v/clawhip.svg" alt="crates.io" /></a>
- <a href="https://github.com/Yeachan-Heo/clawhip/stargazers"><img src="https://img.shields.io/github/stars/Yeachan-Heo/clawhip?style=social" alt="GitHub stars" /></a>
- </p>
- > **⭐ 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.
- ```toml
- # ~/.clawhip/config.toml
- [[routes]]
- event = "github.pr-status-changed"
- filter = { repo = "my-app" }
- sink = "discord"
- channel = "PROJECT_CHANNEL_ID"
- format = "compact"
- ```
- Example event shape:
- ```json
- {
- "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.
- ```toml
- # ~/.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:
- ```json
- {
- "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.
- ```toml
- # ~/.clawhip/config.toml
- [[routes]]
- event = "agent.approval-requested"
- filter = { repo = "my-app" }
- sink = "discord"
- channel = "APPROVAL_CHANNEL_ID"
- format = "alert"
- ```
- Example approval event:
- ```json
- {
- "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:
- ```text
- 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`](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:
- ```bash
- 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 `<repo>/.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:
- ```bash
- clawhip deliver --session <tmux-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-architecture.md)
- - [docs/memory-offload-guide.md](docs/memory-offload-guide.md)
- - [docs/examples/MEMORY.example.md](docs/examples/MEMORY.example.md)
- - [skills/memory-offload/SKILL.md](skills/memory-offload/SKILL.md)
- Runtime support now includes a small bootstrap/inspection surface:
- ```bash
- # 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:
- ```bash
- 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:
- ```text
- @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:
- ```text
- 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](https://discord.com/developers/applications) (e.g. "CCNotifier")
- 2. Copy the bot token
- 3. Invite to your server with **Send Messages** permission
- 4. Set the token in config:
- ```toml
- [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:
- ```bash
- clawhip setup --webhook "https://discord.com/api/webhooks/..."
- ```
- Bounded setup presets also support:
- ```bash
- 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):
- ```bash
- clawhip setup \
- --question-channel "QUESTIONS_CHANNEL_ID" \
- --question-mention "<@OPERATOR_ID>"
- # 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:
- ```toml
- [[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 notify
- 3. Copy the generated `https://hooks.slack.com/services/...` URL into a route
- Route examples:
- ```toml
- [[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"
- ```
- ## Signed HTTP webhook setup
- The generic `http` sink delivers a normalized, bounded, public-safe JSON event directly to a
- local controller such as Hermes. Discord is optional when every event you intend to deliver is
- covered by HTTP, Slack, local-file, or Discord-webhook routes.
- Keep the HMAC secret outside the TOML file and reference its environment-variable name:
- ```bash
- export HERMES_CLAWHIP_HMAC_SECRET="replace-with-a-random-shared-secret"
- ```
- ```toml
- [providers.http]
- endpoint = "http://127.0.0.1:8644/webhooks/clawhip-controller"
- hmac_secret_env = "HERMES_CLAWHIP_HMAC_SECRET"
- [[routes]]
- event = "*"
- sink = "http"
- ```
- The sink signs the exact transmitted bytes with HMAC-SHA256 and sends the result as
- `X-Hub-Signature-256: sha256=<hex>`. `X-Request-ID` is stable for the normalized event and is
- also present in the body. Plain HTTP is accepted only for loopback endpoints (`127.0.0.0/8`,
- `::1`, or `localhost`); non-loopback endpoints must use HTTPS. Redirects are disabled, response
- bodies and endpoint paths are not copied into errors or telemetry, and raw event payloads,
- credentials, local paths, and webhook URLs are excluded or redacted from the outbound body.
- HTTP and Discord can fan out from the same event by adding a second matching route:
- ```toml
- [[routes]]
- event = "github.*"
- sink = "http"
- [[routes]]
- event = "github.*"
- sink = "discord"
- channel = "PROJECT_CHANNEL_ID"
- ```
- ## System model
- ```text
- [CLI / webhook / git / GitHub / tmux]
- -> [sources]
- -> [mpsc queue]
- -> [dispatcher]
- -> [router -> renderer -> Discord/Slack/HTTP sink]
- -> [Discord REST / Slack webhook / signed HTTP 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
- ### GitHub webhook authentication
- Configure a GitHub webhook to POST JSON to the daemon's `/github` endpoint.
- Set the same secret in GitHub's webhook settings and in the daemon's environment:
- ```toml
- [providers.github]
- webhook_secret_env = "CLAWHIP_GITHUB_WEBHOOK_SECRET"
- [daemon]
- bind_host = "127.0.0.1"
- ```
- The config stores only the environment variable name, not the secret. When
- configured, **all** `/github` events require a valid `X-Hub-Signature-256`
- HMAC-SHA256 signature over the exact raw request body. Missing/invalid signatures
- or a missing/empty secret environment variable return `401` without emitting an
- event. JSON parsing and event handling happen only after verification.
- With no secret configured, existing `issues.opened`, release
- (`published`/`released`/`prereleased`/`edited`), and `pull_request.opened`/`closed`
- webhooks retain their unauthenticated behavior. The following activity events
- require a configured secret and valid signature. With no secret configured they
- are ignored with `202` to avoid introducing a new unauthenticated notification
- injection surface (with a configured secret, invalid/missing signatures get `401`):
- | GitHub event/action | Emitted kind |
- | --- | --- |
- | `issue_comment.created` on an issue | `github.issue-commented` |
- | `issue_comment.created` on a PR | `github.pr-commented` |
- | `pull_request_review.submitted` | `github.pr-reviewed` (approved, changes_requested, commented only) |
- | `pull_request_review_comment.created` | `github.pr-review-commented` |
- Edited/deleted comments and other review states/actions are ignored. Activity
- payloads contain identifiers and metadata, never comment/review bodies. Webhooks
- are independent of polling monitor flags, including `emit_pr_activity`.
- For authenticated requests with `X-GitHub-Delivery`, the daemon remembers the last
- 1,000 successful delivery IDs in memory (FIFO). Redeliveries return `202` without
- emitting again. IDs are not persisted across restarts; requests without a delivery
- ID are not deduplicated. Failed requests remain retryable. Enabling both webhook
- activity and `emit_pr_activity` polling for the same repo can produce duplicate
- notifications across those sources; consumers can dedupe PR activity using
- `comment_id`/`review_id`.
- The default bind address is `0.0.0.0`. Prefer `bind_host = "127.0.0.1"` with a
- reverse proxy exposing only `/github` over HTTPS. The webhook secret protects
- `/github`, not other daemon endpoints; do not expose the whole daemon publicly.
- ## Input -> behavior -> verification
- ### 1. Custom client event
- Input:
- ```bash
- 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:
- - authenticated GitHub webhook `issue_comment.created` on an issue (see webhook authentication above)
- - 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:
- - 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.opened` / `pull_request.closed`
- - 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`](docs/native-event-contract.md) for the routing/augmentation
- guide and [`docs/event-contract-v1.md`](docs/event-contract-v1.md) for the frozen shared-event
- reference.
- ### 8. Agent lifecycle preset family
- Input:
- ```bash
- 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:
- ```bash
- clawhip native hook --provider codex --file payload.json
- clawhip native hook --provider claude --file payload.json
- clawhip tmux list
- ```
- Fallback/debug input:
- ```bash
- 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
- clawhip deliver \
- --session <existing-session> \
- --prompt "continue from the latest blocker and open a PR to dev" \
- --max-enters 4
- ```
- 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
- - `deliver` is the prompt recovery path for an already-running hooked tmux-backed provider session
- - `tmux list` shows active daemon-known watches with source, registration timestamp, and parent-process info
- - final delivery still goes through daemon routing
- - `deliver` refuses arbitrary shells and requires prompt-submit-aware hook setup (`clawhip hooks install --provider codex --scope global|project` for Codex, with the bridge in `~/.clawhip`, or `clawhip hooks install --provider claude-code --scope global` for Claude Code)
- 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:
- ```bash
- ./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 pull request activity (opt-in)
- Enable all three activity events on a Git repository monitor:
- ```toml
- [[monitors.git.repos]]
- path = "/path/to/repo"
- github_repo = "owner/repo"
- emit_pr_activity = true
- ```
- `emit_pr_activity` defaults to `false`, including for existing configurations.
- It is independent of `emit_pr_status` and `emit_issue_opened`. When disabled,
- the poller makes no additional requests and continues to ignore PR conversation comments.
- Route these events with `github.*` or their individual kinds:
- | Event | Activity | Extra payload fields |
- | --- | --- | --- |
- | `github.pr-commented` | PR conversation comment | `comment_id` |
- | `github.pr-review-commented` | Inline review comment | `comment_id`, `path` |
- | `github.pr-reviewed` | Submitted review | `review_id`, `state` (`approved`, `changes_requested`, `commented`) |
- All three payloads include `repo`, `number`, `title`, `author`, `pr_author`, and
- `url` (the comment/review permalink). For comments outside the current PR window
- or review scan, the poller resolves the title and PR author with
- `GET /repos/{owner}/{repo}/pulls/{number}`. A 256-entry in-memory FIFO cache avoids
- repeated lookups; window data takes precedence and refreshes cached titles.
- Unknown metadata goes into a shared in-memory FIFO of at most 500 pending
- comments (identifiers, author login, URL, timestamps and inline path, never body
- text). Pending IDs immediately enter their feed's deduplication FIFO. Each poll
- retries pending work oldest-first before reading new comments; remaining lookup
- budget can resolve newly queued work after both feeds are read. A 404 or 410 is
- cached as unavailable and emits with empty `title`/`pr_author` (until cache
- eviction or restart). Other failures, including missing PR authors, retry for at
- most 10 attempts before emitting empty metadata and reporting degraded operation.
- 403/429 use shared rate-limit backoff without consuming an attempt. Queue overflow
- emits the oldest unresolved comment rather than dropping it. Overflow and
- attempt-cap emissions carry empty `title`/`pr_author`, so routes filtering on
- `pr_author` do not match them; routing falls back according to route configuration.
- Overflow, give-up and budget deferral report throttled source degradation.
- The pending queue is in-memory: a restart drops unresolved queued comments.
- `pr_author` can be used in route payload filters to select your PRs. Comment and
- review **body text is never included** in these public-safe event payloads.
- Pending and dismissed reviews are not emitted, nor are edits to old comments.
- API cost per poll: conversation comments use an activity-owned repository
- `/issues/comments` feed; inline comments use the repository `/pulls/comments` feed
- (each up to 10 pages, 100 items/page), independent of the PR list so older PRs are
- still detected. The conversation feed adds one request per poll when unpaginated;
- pending metadata cache misses add at most 20 PR-detail requests per poll, one per
- distinct PR, shared by both comment feeds. Cold baselines never enqueue or look
- up seeded comments. The queue and cache survive CI-baseline persistence failures
- in the running process, but are not persisted across restarts.
- The conversation feed ignores issue comments and does not change the existing issue-comment count-delta
- poller or enable issue polling when disabled. PR conversation IDs have their own bounded deduplication FIFO;
- issue-comment churn or a CI-baseline persistence failure does not replay them.
- Cold start itself emits no activity and does not traverse full history. Conversation and inline
- comments read only the newest page (`sort=updated&direction=desc`) and seed all
- received PR-comment IDs. Reviews read only the newest PR page and seed reviews on PRs sharing
- that page's newest `updated_at`; more than 20 such PRs span polls without emission.
- Each cold fetch's server `Date` establishes its creation/submission eligibility
- lower bound L, falling back to the newest observed update when Date is missing or
- invalid. Later notifications require `created_at` / `submitted_at` >= L and an
- unseen ID, so unseen historical boundary items older than that cutoff do not replay.
- Timestamps have second precision: unseen historical items in the cutoff second
- cannot be distinguished from new same-second activity, especially with the fallback.
- After baseline, each comment feed uses its own updated-at pagination position P
- with ascending updates and `since=P-1s`. The 10-page cap reports source degradation
- and advances P to the last received update, but holds creation eligibility L fixed
- until the backlog drains. Thus a newly created comment edited before its first
- delivery is still eligible even when its creation precedes P. A completed fetch
- advances L to the maximum consumed update (never backwards); all updates through
- that position have been consumed. A failed fetch preserves both P and L. Only
- delivered, queued or deliberately seeded cold IDs enter the deduplication FIFO.
- Metadata availability never stops a feed or freezes P/L: pending comments retain
- their original eligibility independently of later feed positions. Both comment
- kinds share one pending FIFO, so new conversation comments cannot starve older
- inline comments of lookup budget. All requests remain subject to the shared
- GitHub rate-limit backoff.
- Reviews build a separate updated-desc PR window (up to 5 pages, 500 PRs), stopping
- only below the committed submission watermark. Boundary-second PRs are always
- rechecked; review IDs prevent duplicate notifications. A scan stores its fixed
- submission lower bound and pending PRs, fetching at most 20 PRs per poll (up to
- 10 pages of reviews per PR), oldest update first. No PR-list request is needed
- while that scan drains. The watermark advances to the window's newest PR update
- only when every pending PR succeeds; an individual failure or review-page cap
- reports throttled source degradation, requeues that PR, and retains the watermark.
- Thus reviews submitted before a PR's later update are not lost across scan polls.
- If more than 500 PRs have updated since the watermark, the PR-list cap still
- processes the newest 500-PR window and commits its upper bound on completion.
- It explicitly reports source degradation: **reviews on PRs outside that window
- may be lost**, rather than allowing a permanent backlog to starve progress.
- Pagination is not a transactional snapshot. Deduplication is in-memory and
- bounded to 1,000 IDs per activity kind; overlapping windows larger than that
- cache can replay IDs. Exactly 1,000 updates in either comment feed at the inclusive cursor second
- can fill every resumable window and block any later comment (as can larger ties).
- The conversation feed shares GitHub's `/issues/comments` endpoint with issue
- comments: filtering issue comments does not remove their pagination cost, so they
- occupy the same page slots and 10-page budget. A burst of issue comments can delay
- PR conversation notifications, and 1,000 issue comments tied at the cursor second
- can stall them as above.
- A PR with over 1,000 reviews can keep its
- scan waiting at the per-PR page cap. Restarting establishes fresh baselines.
- ## GitHub notifications (opt-in, across all repositories)
- Poll the authenticated user's notification inbox without configuring repositories
- or fetching PR metadata. This complements, rather than replaces, `emit_pr_activity`.
- Only activity GitHub places in your notification inbox is observed (including
- your PRs/issues, mentions and review requests); it is not a repository-wide audit log.
- ```toml
- [monitors.github_notifications]
- enabled = true # default false: zero requests when disabled
- poll_interval_secs = 60 # min 1; max(configured, latest valid X-Poll-Interval)
- participating = false # true sends participating=true
- reasons = [] # empty = all; e.g. ["author", "mention", "review_requested"]
- repos = [] # empty = all; e.g. ["owner/repo"]
- # channel = "CHANNEL_ID" # optional direct destination
- # channel_name = "development"
- # mention = "<@USER_ID>"
- format = "compact"
- [[routes]]
- event = "github.notification"
- filter = { reason = "review_requested", subject_type = "PullRequest" }
- channel = "REVIEW_CHANNEL_ID"
- ```
- Credentials use `CLAWHIP_GITHUB_TOKEN`, then `monitors.github_token`, then
- `gh auth token`. GitHub's [notifications REST documentation](https://docs.github.com/en/rest/activity/notifications)
- currently documents personal access tokens **(classic)** with `notifications` or
- `repo` scope; this endpoint does **not** support fine-grained personal access tokens.
- Authenticate `gh` with a credential that can read notifications.
- Each poll constructs at most five `GET /notifications` requests, with `all=true`,
- `participating` as configured, and `per_page=50`. Read threads are included, so
- an update read elsewhere before the next poll is still delivered once; delivery
- depends on the watermark and thread dedup, never on GitHub's unread flag. Constructed polling/pagination
- requests stay on the configured API origin; HTTP 3xx redirects retain the shared
- GitHub client's default behavior and can add transport requests or change origin.
- The committed watermark W advances only to the greatest `updated_at` actually
- received in a completed scan, never from the response `Date` or an incomplete
- fresh head page. Empty/older responses leave W unchanged; before any update has
- been covered, W is unset and requests omit `since`. Normal polls request
- `since=W-5m`. This fixed reconciliation overlap tolerates response generation
- latency, visibility lag and clock disagreement totaling less than five minutes;
- updates arriving behind that window are not guaranteed to be observed. Repeated
- updates are deduplicated by thread ID and `updated_at`. Conditional requests use
- `If-Modified-Since` no later than either the previous complete response's
- `Last-Modified` or W minus five minutes (the cold-start cutoff minus five minutes
- when W is unset), so a later response header cannot hide the overlap.
- An authenticated `304 Not Modified` emits nothing and does not consume the
- primary rate limit. In steady state these conditional savings are mostly
- unavailable: the conditional time is clamped to W minus five minutes, usually
- earlier than the inbox's last modification, so GitHub returns `200`. A `200`
- consumes the primary rate limit; at the default 60-second interval, one to five
- requests per poll is roughly 60–300 requests/hour of the authenticated
- 5,000/hour budget. Conditional times use the UTC IMF-fixdate HTTP-date format.
- The effective interval is
- the maximum of the configured interval and the **latest valid** `X-Poll-Interval`,
- including headers on failures and 304 responses; a later lower value reduces the
- delay again. Missing/invalid interval headers retain the latest valid value.
- Shared GitHub 403/429 backoff also applies.
- A five-page cap reports throttled source degradation and saves a catch-up window
- without advancing W. A catch-up that starts before W is set (for example, read
- history exceeding five pages on the cold poll) uses the cold-start cutoff in
- place of W, because older updates are never delivered; the baseline does not
- drain the whole read history. Outside a pinned tie, every catch-up poll first fetches one
- fresh head page with `since=<W at catch-up start>-5m`, so its newest 50 updates are not delayed
- by the backlog. The remaining four requests drain that same lower bound with
- `before=<oldest received updated_at + 1s>`. The head and backlog windows overlap,
- with no timestamp gap. Normal continuation uses only timestamps, restarting
- pagination at page one each poll; reading/updating earlier threads cannot shift
- a saved page offset past unseen older threads. Local reason/repo filters never
- advance or truncate the scan. Once the backlog is proven complete, W advances
- to the greatest update covered by that scan, excluding the incomplete head.
- The next normal scan therefore includes head overflow. Conditional requests are
- disabled throughout catch-up and on that first normal scan.
- HTTP/decoding failures and missing/invalid first-page Date headers preserve the
- watermark, continuation, thread baseline, and conditional cursor.
- **Oversized boundary-second limitation:** if more than 200 threads share
- the boundary `updated_at` second, they cannot all be reconciled in the four
- backlog requests. Bounded page offsets enumerate only that second, then restart
- at page one when they reach its end. Such cross-poll offsets never prove
- completion: contractions can skip an ID during one pass, but subsequent passes
- revisit it once the inbox stabilizes. W remains pinned and older backlog waits
- until a page-one scan proves the entire boundary second fits in one poll. The
- available tie budget determines how many pages that proof can cover.
- While pinned at second T, newer delivery has its own timestamp-only scan of
- `(T, now]`, using exclusive `since=T`. Every poll first fetches page one of this
- fresh head, even with a saved newer cursor. Up to three following requests go
- to newer-range pagination, leaving **at least one request for enumerating T**;
- unused newer requests go to T. An empty newer head leaves four tie pages only
- when no newer continuation is saved; an empty stale continuation costs one
- request, is then cleared, and leaves three tie pages. A
- newer scan starting afresh reuses the head as its first page. If it does not
- finish, it saves `before=<oldest received updated_at + 1s>` and restarts at page
- one of that timestamp window next poll, deduplicating the overlap by thread ID
- and `updated_at`. If a continuation exhausts its budget without moving `before`
- strictly older than its starting value, that stalled cursor is cleared so the
- next poll restarts from the fresh head. On completion it also restarts fresh
- next poll. This delivery scan
- never advances W or proves tie coverage. Thus, once the inbox stabilizes, a
- newer range with distinct timestamps drains across polls while T also receives
- enumeration requests; fresh head overflow cannot wait forever behind T.
- **Nested newer-tie limitation:** this newer-range delivery scan does not
- recursively enumerate oversized same-second groups. A group of more than 200
- newer threads at one second cannot fit its restarting budget (head plus three
- pages); a saved continuation has only three pages, so even a group of more than
- 150 threads at its boundary can stall it. Restarting a stalled cursor prevents
- distinct-timestamp arrivals above that group from being stranded between the
- head and the saved boundary: once the inbox freezes, each continuation either
- moves older or restarts a head-based scan. In the 201-thread nested-group case,
- 51 distinct arrivals above it all arrive within two successful polls (one to
- clear the stalled cursor, then one head-based scan to reach the 51st arrival).
- Unseen threads inside or below the oversized nested second can still wait
- indefinitely until the group shrinks; restarting does not enumerate that group
- recursively or prove its coverage. The fresh head and the original T enumeration
- still run, with W conservatively pinned.
- Avoiding recursive cursor trees keeps state and request allocation bounded;
- this is a delivery limitation, not a claim of complete coverage.
- Pinned ties can persist indefinitely and cost up to five constructed requests
- per poll, with throttled degradation reporting rather than unbounded requests.
- Even without oversized ties, more than 250 threads in the five-minute overlap
- can repeatedly trigger catch-up, at the same per-poll request bound.
- **Unread only; never marks read.** No PATCH/PUT requests are made. Reading a
- notification on github.com removes it from the unread feed; further activity
- re-surfaces it with a newer `updated_at`. The first successful poll seeds a
- baseline without replaying history. Its server `Date` is the eligibility cutoff
- (missing/invalid Date defers initialization). Subsequent polls emit one
- `github.notification` per thread whose `updated_at` advances, not per comment.
- An unseen thread older than that cutoff never replays unless it changes.
- The in-memory dedupe FIFO holds 1,000 threads; eviction can replay a post-cutoff
- thread within the reconciliation overlap or a repeatedly scanned oversized tie.
- Restarting establishes a fresh, silent baseline. GitHub's inbox is not a snapshot:
- continuous mutation during requests can delay observation, and updates must
- remain unread/visible to be fetched. Separate changes to one thread with the same
- second-resolution `updated_at` cannot be distinguished.
- Payloads contain no comment/review bodies, token, or private credential metadata.
- Repository names and titles can still identify private repositories: route only
- to destinations authorized to see the authenticated user's inbox.
- | Field | Meaning |
- | --- | --- |
- | `repo` | `owner/repo` |
- | `thread_id` | GitHub notification thread ID (string) |
- | `reason` | GitHub reason, e.g. `author`, `comment`, `mention`, `review_requested`, `assign`, `state_change`, `team_mention`, `ci_activity` |
- | `subject_type` | GitHub type, e.g. `PullRequest`, `Issue`, `Discussion`, `Release`, `CheckSuite`, `Commit` |
- | `title` | Subject title, never its body |
- | `number` | Optional issue/PR/discussion number derived without another request |
- | `url` | Derived HTML URL, with a comment anchor when determinable; otherwise repository URL |
- | `updated_at` | GitHub thread update timestamp |
- ## Preset event families
- ### GitHub family
- - `github.notification`
- - `github.issue-opened`
- - `github.issue-commented`
- - `github.issue-closed`
- - `github.pr-commented`
- - `github.pr-review-commented`
- - `github.pr-reviewed`
- - `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:
- ```text
- ~/.clawhip/config.toml
- ```
- Route model:
- ```toml
- [[routes]]
- event = "github.*"
- filter = { repo = "clawhip" }
- sink = "discord"
- channel = "PROJECT_CHANNEL_ID"
- mention = "@maintainer-or-team"
- format = "compact"
- allow_dynamic_tokens = false
- [[routes]]
- event = "session.*"
- filter = { tool = "omx", repo_name = "clawhip" }
- sink = "discord"
- channel = "PROJECT_CHANNEL_ID"
- format = "compact"
- allow_dynamic_tokens = false
- [[routes]]
- event = "session.*"
- filter = { tool = "omx", repo_name = "clawhip", session_id = "sess-123" }
- sink = "discord"
- thread = "DISCORD_THREAD_ID"
- format = "compact"
- allow_dynamic_tokens = false
- [[routes]]
- event = "agent.*"
- filter = { project = "clawhip" }
- sink = "discord"
- channel = "PROJECT_CHANNEL_ID"
- 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
- Discord thread targets:
- - Use `thread = "DISCORD_THREAD_ID"` on a Discord route to deliver directly into
- a thread. This is explicit; clawhip does not infer threads from `channel` IDs,
- names, session labels, or payload fields.
- - A Discord route may set exactly one delivery target: `channel`, `thread`, or
- `webhook`.
- - Thread delivery uses the configured thread ID as the Discord message target.
- If Discord reports the thread as archived, missing, forbidden, or otherwise
- unreachable, clawhip records a concise delivery error and does **not**
- automatically fall back to the parent channel.
- - Diagnostics and binding verification only reference configured IDs and status
- outcomes; clawhip does not list or dump private channel/thread inventories.
- ## Gateway allowlist diagnostics
- When clawhip sends through a local Clawdbot gateway, route channel IDs must also
- be present in the gateway's Discord allowlist. Check that boundary with:
- ```bash
- clawhip config verify-gateway-allowlist
- clawhip config verify-gateway-allowlist --gateway-config ~/.clawdbot/clawdbot.json
- clawhip config verify-gateway-allowlist --json
- ```
- The default gateway config path is `~/.clawdbot/clawdbot.json` when `HOME` is
- available; use `--gateway-config <path>` for any other local file. The command
- reads only `channels.discord.guilds[*].channels.<channel_id>.allow = true`,
- compares it with clawhip's configured Discord channel destinations, and exits
- non-zero when any destination is missing or not explicitly allowed.
- Output is public-safe by design: text and JSON reports include counts, clawhip
- source labels, and channel IDs only. They do not dump gateway tokens, webhook
- URLs, raw config payloads, or unrelated gateway fields. Discord/Slack webhooks, HTTP routes,
- localfile routes, and thread-only targets are outside this allowlist check.
- ## Dynamic token contract
- Only for routes with:
- ```toml
- 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
- ```bash
- cargo install clawhip
- ```
- Published at [crates.io/crates/clawhip](https://crates.io/crates/clawhip). Requires Rust toolchain.
- ### Prebuilt binary installer (recommended, no Rust needed)
- ```bash
- 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
- ```bash
- ./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. After a source fallback, it invokes the installed binary to validate the exact clawhip git checkout and persist the managed deployment-health sidecar without modifying operator config; the install fails if that recording step cannot complete. A relative `CLAWHIP_CONFIG` is resolved from the directory that invoked the script. Both the script recording path and regular `clawhip install --config ...` prepare only the selected config parent hierarchy, so custom installs do not depend on or mutate the default `$HOME/.clawhip`. 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
- ```bash
- 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:
- ```text
- deploy/clawhip.service
- ```
- Expected install path:
- - copy to `/etc/systemd/system/clawhip.service`
- - `systemctl daemon-reload`
- - `systemctl enable --now clawhip`
- ## Deployed build identity
- The crate version only changes on release, so `clawhip 0.6.11` cannot tell a
- freshly deployed daemon apart from one still running a binary built several
- merges earlier. Every build therefore stamps the source revision it was built
- from, and both the CLI and the daemon report it:
- ```bash
- clawhip --version
- # clawhip 0.6.11 (7bad9d24df18) built from that commit
- # clawhip 0.6.11 (7bad9d24df18-dirty) build tree had uncommitted changes
- # clawhip 0.6.11 revision unavailable (e.g. source tarball)
- curl -s localhost:25294/health | jq .build
- # { "version": "0.6.11", "commit": "7bad9d24df18...", "short_commit": "7bad9d24df18",
- # "dirty": false, "commit_source": "git" }
- ```
- Compare `build.commit` against the revision you expect to have deployed to
- confirm a rollout landed instead of inferring it from a green repository state.
- When `[update].repo_root` is configured the daemon makes that comparison
- itself — see [Deployment drift alerts](#deployment-drift-alerts).
- `commit_source` is `git` for checkout builds, `environment` when a packaging
- pipeline supplies `CLAWHIP_BUILD_COMMIT` (or CI supplies `GITHUB_SHA`), and
- `unavailable` when no revision could be determined. Only the commit object
- name, a dirty flag, and that source are exposed — no branches, paths, or
- hostnames. A build without `git` or outside a checkout still succeeds.
- ## Deployment drift alerts
- Knowing the build revision only helps if somebody compares it. When
- `[update].repo_root` points at the source checkout, the daemon does that
- comparison itself every 5 minutes and alerts once per newly observed drift
- pair:
- ```
- clawhip deployment drift: running binary was built from c4774562c6b0,
- but the source checkout is at dd1494cc0f4d.
- The running service is not the code in the checkout; rebuild and restart to deploy it.
- ```
- The alert is delivered like any other custom event (`[update].channel` selects
- the target), and the latest observation is always readable:
- ```bash
- curl -s localhost:25294/health | jq .deployment
- # { "state": "drift", "binary_commit": "c4774562...", "source_commit": "dd1494cc...", "reason": null }
- ```
- `state` is one of:
- | state | meaning |
- | --- | --- |
- | `match` | the running binary was built from the checkout's current `HEAD` |
- | `drift` | the binary was built from a different revision; **alerts** |
- | `unknown` | not comparable; never alerts, and `reason` says why |
- `unknown` is deliberate rather than a silent pass. It is reported when no
- checkout is configured, when `HEAD` is unreadable (missing directory, not a
- repository), when the binary carries no stamped revision (e.g. a crates.io or
- tarball build), or when the binary was built from a modified tree — a `-dirty`
- build provably is not exactly its commit, so it is never called a match.
- Only commit object names are exposed; the checkout path never appears in an
- event payload or on the health surface.
- ## Live verification runbook
- Use:
- - `docs/live-verification.md`
- - `scripts/live-verify-default-presets.sh`
- - `scripts/internal-pr-format-gate.sh` for cheap local format gating before internal PR create/update flows
- 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
- ```bash
- clawhip # start daemon
- clawhip --version # crate version + build revision of this binary
- clawhip status # daemon health
- clawhip config # bounded preset editor / config inspection
- clawhip config verify-gateway-allowlist # check Clawdbot gateway allowlist coverage
- 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
- clawhip gajae status # check local GAJAE CLI bridge availability
- ```
- ## GAJAE CLI bridge
- `clawhip gajae` provides a small Rust CLI bridge for local GAJAE dogfooding:
- ```bash
- clawhip gajae status
- clawhip gajae profile install
- clawhip gajae preflight
- clawhip gajae doctor --repo owner/repo
- clawhip gajae profile verify
- ```
- `status` discovers GAJAE from `GAJAE_BIN` first, then the `gajae` executable on `PATH`, and verifies it by running `gajae --help`. `profile install` forwards to `gajae clawhip profile install` with stdout/stderr attached so GAJAE owns the profile update flow. `preflight` is the #257 public-safe readiness check: it verifies GAJAE discovery, required receipt validators, the installed clawhip profile, public-safe output mode, and disabled raw-payload export, then prints a concise JSON summary safe to paste into issues or PRs. Preflight does not mutate cron/config, does not contact GitHub, and does not require GAJAE for baseline clawhip routing. `doctor` extends those bounded diagnostics with schema capability, handler-command drift, and optional dry-run onboard-plan checks. `profile verify` checks the installed profile and handler commands without executing routes. Doctor and verify never run `gajae clawhip profile install` and never mutate live profiles.
- GAJAE route handlers are daemon-side and default off. Enable them explicitly and attach a bounded handler to an approved route:
- ```toml
- [gajae]
- handlers_enabled = true
- handler_timeout_ms = 5000
- handler_max_output_bytes = 16384
- [[routes]]
- event = "github.pr-*"
- filter = { repo = "clawhip" }
- sink = "discord"
- channel = "OPS_CHANNEL_ID"
- gajae = { subcommand = "handle-event", args = ["--profile", "safe"] }
- ```
- Handler execution uses the `GAJAE_BIN` override or `gajae` on `PATH`, runs only fixed allowlisted GAJAE handler subcommands, passes the event JSON on child stdin, closes parent stdin, enforces timeout/output caps, and emits `gajae.handler.completed`, `gajae.handler.failed`, `gajae.handler.timeout`, or `gajae.handler.approval-required` through normal routing. Handler output is data-only; mutation-shaped output is converted to an approval-required event instead of being applied automatically.
- ## Internal PR fast-path
- Before opening or updating an internal PR from a Rust worktree, run:
- ```bash
- scripts/internal-pr-format-gate.sh
- ```
- If you already know the tree just needs formatting, auto-fix first:
- ```bash
- scripts/internal-pr-format-gate.sh --fix
- ```
- This catches the cheapest class of red CI (`cargo fmt` only) locally before PR create/update churn.
- ## GEO visibility benchmark
- clawhip includes a [`geobench`](https://github.com/NomaDamas/geobench) product spec for measuring LLM hit rate, MRR, share of voice, and citations for event-to-channel AI-agent operations queries.
- - Spec: [`geobench/clawhip.yaml`](geobench/clawhip.yaml)
- - Runbook: [`docs/geobench.md`](docs/geobench.md)
- ## GitHub Actions platform status monitor
- Poll the public GitHub Statuspage machine-readable API for GitHub Actions (and optionally other components) without using GitHub API tokens or websocket subscriptions.
- This is a daemon monitor (`monitors.github_status`), **not** a `[[subscriptions]]` websocket worker. Keep it separate from GJC workflow-gate / question subscriptions.
- Official public endpoints (no auth, no secrets):
- - `https://www.githubstatus.com/api/v2/summary.json`
- - `https://www.githubstatus.com/api/v2/status.json`
- - `https://www.githubstatus.com/api/v2/components.json`
- - `https://www.githubstatus.com/api/v2/incidents.json`
- `status.github.com` serves the same Statuspage surface; clawhip defaults to the `www.githubstatus.com` API base.
- ```toml
- [monitors.github_status]
- enabled = true
- # Public Statuspage API; no token. Override only for tests/mirrors.
- api_base = "https://www.githubstatus.com/api/v2"
- components = ["Actions"]
- poll_interval_secs = 60
- # Optional direct channel; prefer an explicit route for gajae-code dev.
- # channel = "YOUR_GAJAE_CODE_DEV_CHANNEL_ID"
- # channel_name = "gajae-code-dev"
- format = "alert"
- [[routes]]
- event = "github.actions-*"
- sink = "discord"
- channel = "YOUR_GAJAE_CODE_DEV_CHANNEL_ID"
- channel_name = "gajae-code-dev"
- format = "alert"
- ```
- Events:
- - `github.actions-status` — watched component transitions among `degraded_performance`, `partial_outage`, `major_outage`, `under_maintenance`, and recovery to `operational`
- - `github.actions-incident` — incident opened / update / resolved for incidents that affect a watched component
- Anti-spam:
- - first successful poll establishes a baseline and emits nothing
- - stable component status and identical incident update IDs do not re-alert
- - only lifecycle deltas (status change, new update id, resolve) emit
- ## Websocket subscriptions
- Subscriptions are daemon-owned, guarded local ingress for a configured websocket event stream. Keep endpoint credentials outside the TOML file: the configuration names an environment variable, and `clawhip subscribe`, health, and API responses never print that name, its value, the endpoint URL, adapter arguments, adapter stderr, frames, or adapter output.
- Set the endpoint only in the daemon environment, then keep the subscription policy and route ownership in `~/.clawhip/config.toml`:
- ```bash
- export GJC_WORKFLOW_GATE_WS='wss://localhost:9443/gjc-events'
- clawhip subscribe validate
- clawhip start
- ```
- ```toml
- [[subscriptions]]
- name = "gjc-workflow-gate"
- enabled = true
- kind = "websocket"
- endpoint_env = "GJC_WORKFLOW_GATE_WS"
- [subscriptions.filter]
- discriminator_pointer = "/type"
- discriminator_equals = "workflow_gate"
- [[subscriptions.filter.predicates]]
- pointer = "/gate/state"
- equals = "ready"
- [subscriptions.projection]
- workflow_id = "/workflow/id"
- gate_state = "/gate/state"
- [subscriptions.adapter]
- program = "/absolute/path/to/gjc-workflow-gate-adapter"
- args = []
- [subscriptions.routing]
- tool = "gjc"
- project = "my-project"
- [[routes]]
- event = "workflow.gate"
- sink = "discord"
- channel = "WORKFLOW_GATE_CHANNEL_ID"
- format = "alert"
- ```
- A separate `question` subscription remains explicit and route-owned; it must not share a workflow-gate filter or silently inherit its channel:
- ```toml
- [[subscriptions]]
- name = "gjc-question"
- enabled = true
- kind = "websocket"
- endpoint_env = "GJC_QUESTION_WS"
- [subscriptions.filter]
- discriminator_pointer = "/type"
- discriminator_equals = "question"
- [subscriptions.projection]
- question_id = "/question/id"
- summary = "/question/summary"
- [subscriptions.adapter]
- program = "<path-to-clawhip>"
- args = ["subscribe", "adapter", "question"]
- [[routes]]
- event = "workflow.question"
- sink = "discord"
- channel = "QUESTIONS_CHANNEL_ID"
- format = "compact"
- ```
- Use `clawhip subscribe list`, `clawhip subscribe status <name>`, `clawhip subscribe start <name>`, and `clawhip subscribe stop <name>` only against a loopback daemon. The daemon also enforces the loopback peer and numeric loopback `Host` checks. `start` and `stop` additionally require the fixed `x-clawhip-local-control: 1` request header (sent automatically by `clawhip`) and reject non-loopback `Origin` headers; this is a local browser-CSRF and DNS-rebinding guard, not a credential. Redirects are not followed. `start` and `stop` are idempotent and return a reason code. Enabled subscriptions reconnect with their configured bounded backoff; daemon shutdown cancels workers and waits a bounded time before aborting remaining work.
- Adapters receive only the selected projection on stdin and must emit exactly one bounded JSON object with `type` and object `payload` on stdout. They run with a cleared environment; do not depend on inherited credentials or emit logs on stdout. Route channels belong in `[[routes]]`, not in subscription frames or adapter output.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.