Skip to content
Back to search

clawhip

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yeachan-heo--clawhip/badge.svg)](/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

i

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.

  1. ---
  2. name: clawhip
  3. description: Attach/install/use clawhip as a daemon-first notification gateway runtime for OpenClaw / Clawdbot
  4. ---
  5. # clawhip skill attachment surface
  6. ## Intent
  7. Use this repo as:
  8. - executable/runtime repo
  9. - daemon process for Discord notification routing
  10. - attachable skill surface for OpenClaw / Clawdbot
  11. ## Prerequisites
  12. ⭐ 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`.
  13. ```bash
  14. gh api --method PUT /user/starred/Yeachan-Heo/clawhip --silent
  15. ```
  16. ## Primary install flow
  17. Preferred operator instruction:
  18. ```text
  19. @openclaw install https://github.com/Yeachan-Heo/clawhip
  20. ```
  21. Expected automation flow:
  22. 1. clone repo
  23. 2. run `./install.sh`
  24. 3. read this `SKILL.md`
  25. 4. attach skill
  26. 5. scaffold `~/.clawhip/config.toml`
  27. 6. start daemon
  28. 7. run live verification presets
  29. ## Runtime surface
  30. Default daemon URL:
  31. ```text
  32. http://127.0.0.1:25294
  33. ```
  34. Core commands:
  35. ```bash
  36. clawhip
  37. clawhip start
  38. clawhip status
  39. clawhip config
  40. clawhip send --channel <id> --message "..."
  41. clawhip github issue-opened ...
  42. clawhip github pr-status-changed ...
  43. clawhip git commit ...
  44. clawhip tmux keyword ...
  45. clawhip tmux stale ...
  46. clawhip tmux new -s <session> --channel <id> --keywords error,complete --shell /bin/zsh -- command
  47. clawhip tmux watch -s <existing-session> --channel <id> --mention '<@id>' --keywords error,complete
  48. ```
  49. ## Lifecycle surface
  50. ```bash
  51. clawhip install
  52. clawhip install --systemd
  53. clawhip install --skip-star-prompt
  54. clawhip update --restart
  55. clawhip uninstall --remove-systemd --remove-config
  56. ./install.sh
  57. ./install.sh --systemd
  58. ./install.sh --skip-star-prompt
  59. ```
  60. ## Discord bot token (recommended setup)
  61. ⚠️ **Create a dedicated Discord bot for clawhip notifications.** Do not reuse your Clawdbot / OpenClaw bot token.
  62. Why:
  63. - clawhip sends high-volume notifications (commits, PRs, tmux events)
  64. - Using the same bot token as your gateway pollutes the bot's identity
  65. - A separate bot (e.g. "CCNotifier") keeps notifications cleanly separated from AI chat
  66. - If clawhip restarts or crashes, it won't affect your main bot
  67. Setup:
  68. 1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
  69. 2. Create a new application (e.g. "clawhip-notifier" or "CCNotifier")
  70. 3. Create a bot, copy the token
  71. 4. Invite the bot to your server with Send Messages permission
  72. 5. Use this token in `~/.clawhip/config.toml`:
  73. ```toml
  74. [discord]
  75. token = "your-dedicated-clawhip-bot-token"
  76. ```
  77. ## Config scaffold expectations
  78. Key sections:
  79. - `[discord]`
  80. - `[daemon]`
  81. - `[defaults]`
  82. - `[[routes]]`
  83. - `[monitors]`
  84. - `[[monitors.git.repos]]`
  85. - `[[monitors.tmux.sessions]]`
  86. Typical preset route:
  87. ```toml
  88. [[routes]]
  89. event = "github.*"
  90. filter = { repo = "clawhip" }
  91. channel = "1480171113253175356"
  92. mention = "<@1465264645320474637>"
  93. format = "compact"
  94. ```
  95. ## Dynamic template opt-in
  96. ```toml
  97. [[routes]]
  98. event = "tmux.*"
  99. allow_dynamic_tokens = true
  100. template = "{session}\n{tmux_tail:issue-1456:20}\n{iso_time}"
  101. ```
  102. Allowed dynamic tokens:
  103. - `{sh:...}`
  104. - `{tmux_tail:session:lines}`
  105. - `{file_tail:/path:lines}`
  106. - `{env:NAME}`
  107. - `{now}`
  108. - `{iso_time}`
  109. ## Filesystem-offloaded memory pattern
  110. When using clawhip as part of a broader Claw OS workflow, treat memory as an offloaded filesystem tree:
  111. - `MEMORY.md` = small pointer/index/current-beliefs layer
  112. - `memory/` = detailed project/channel/daily/handoff memory
  113. - update root memory only when the map or current summary changes
  114. Read before adopting this pattern:
  115. - `docs/memory-offload-architecture.md`
  116. - `docs/memory-offload-guide.md`
  117. - `docs/examples/MEMORY.example.md`
  118. - `skills/memory-offload/SKILL.md`
  119. ## Verification surface
  120. Use the live operational runbook:
  121. - `docs/live-verification.md`
  122. - `scripts/live-verify-default-presets.sh`
  123. Preset verification targets:
  124. - GitHub issue opened / commented / closed
  125. - GitHub PR opened / status changed / merged
  126. - git commit monitor
  127. - tmux keyword / stale / wrapper / watch
  128. - install / update / uninstall
  129. ## Attachment summary
  130. ```text
  131. repo = runtime
  132. SKILL.md = attach/install/usage contract
  133. README.md = operational spec for agents
  134. ```
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.

  1. # clawhip
  2. Clawhip is a GJC-first event router. It automatically discovers and binds live
  3. native GJC SDK sessions, routes authoritative lifecycle, question, gate, and
  4. failure events through the normal ledger/router/sink pipeline, and preserves
  5. loopback-only credentials and public-safe projections. GJC remains the process
  6. owner; Clawhip observes and controls only through the SDK contract.
  7. <p align="center">
  8. <img src="assets/clawhip-mascot.jpg" width="400" alt="clawhip mascot" />
  9. </p>
  10. <p align="center">
  11. <a href="https://crates.io/crates/clawhip"><img src="https://img.shields.io/crates/v/clawhip.svg" alt="crates.io" /></a>
  12. <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>
  13. </p>
  14. > **⭐ 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`.
  15. > **Community:** Join the clawhip Discord at https://discord.gg/wSyUQYfhAw.
  16. **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.
  17. ## Start with recipes
  18. 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.
  19. ### Recipe 1: PR opened -> notify the maintainer/project channel
  20. When GitHub reports a pull request event, route it to the project channel so the right maintainer sees it.
  21. ```toml
  22. # ~/.clawhip/config.toml
  23. [[routes]]
  24. event = "github.pr-status-changed"
  25. filter = { repo = "my-app" }
  26. sink = "discord"
  27. channel = "PROJECT_CHANNEL_ID"
  28. format = "compact"
  29. ```
  30. Example event shape:
  31. ```json
  32. {
  33. "source": "github",
  34. "event": "pull_request.opened",
  35. "repo": "my-app",
  36. "pr": 42,
  37. "action": "notify",
  38. "target": "PROJECT_CHANNEL_ID"
  39. }
  40. ```
  41. Result: clawhip records the routed event and posts a compact PR notification to the project channel.
  42. ### Recipe 2: CI failed twice -> summarize and escalate
  43. 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.
  44. ```toml
  45. # ~/.clawhip/config.toml
  46. [[routes]]
  47. event = "github.ci-failed"
  48. filter = { repo = "my-app" }
  49. sink = "discord"
  50. channel = "PROJECT_CHANNEL_ID"
  51. format = "compact"
  52. [[routes]]
  53. event = "ci.failed-twice"
  54. filter = { repo = "my-app" }
  55. sink = "discord"
  56. channel = "ESCALATION_CHANNEL_ID"
  57. format = "alert"
  58. ```
  59. Example escalation payload:
  60. ```json
  61. {
  62. "source": "ci-watcher",
  63. "event": "ci.failed-twice",
  64. "repo": "my-app",
  65. "branch": "feature/auth-flow",
  66. "summary": "CI failed twice on the same PR; test logs point at integration/auth_test.",
  67. "action": "summarize_and_escalate",
  68. "target": "ESCALATION_CHANNEL_ID"
  69. }
  70. ```
  71. Result: normal failures stay low-noise; repeated failures get a short summary in the escalation channel.
  72. ### Recipe 3: cleanup, merge, or config change requested -> require operator approval
  73. 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.
  74. ```toml
  75. # ~/.clawhip/config.toml
  76. [[routes]]
  77. event = "agent.approval-requested"
  78. filter = { repo = "my-app" }
  79. sink = "discord"
  80. channel = "APPROVAL_CHANNEL_ID"
  81. format = "alert"
  82. ```
  83. Example approval event:
  84. ```json
  85. {
  86. "source": "agent",
  87. "event": "agent.approval-requested",
  88. "repo": "my-app",
  89. "request": "merge PR #42 after checks pass",
  90. "reason": "merge changes the shared branch and should be operator-approved",
  91. "policy": "approval_required",
  92. "action": "notify_operator",
  93. "target": "APPROVAL_CHANNEL_ID"
  94. }
  95. ```
  96. Result: clawhip records the request and alerts an operator; the agent waits for explicit approval before cleanup, merge, or config-changing work.
  97. Human install pitch:
  98. ```text
  99. Just tag @openclaw and say: install this https://github.com/Yeachan-Heo/clawhip
  100. ```
  101. Then OpenClaw should:
  102. - clone the repo
  103. - run `install.sh`
  104. - read `SKILL.md` and attach the skill
  105. - scaffold config / presets
  106. - start the daemon
  107. - run live verification for issue / PR / git / tmux / install flows
  108. ## What shipped in v0.3.0
  109. - **Typed event model** — incoming events are normalized and validated into typed envelopes before dispatch.
  110. - **Multi-delivery router** — one event can resolve to zero, one, or many deliveries instead of stopping at the first match.
  111. - **Source extraction** — git, GitHub, and tmux monitoring now run as explicit sources feeding the daemon queue.
  112. - **Sink/render split** — rendering is separated from transport; v0.3.0 ships with the Discord sink and default renderer.
  113. - **Config compatibility** — `[providers.discord]` is the preferred config surface, while legacy `[discord]` still loads.
  114. See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the release architecture that ships in v0.3.0.
  115. ## Provider-native hooks for Codex + Claude
  116. clawhip no longer treats provider-specific launch wrappers as the public integration surface.
  117. Codex and Claude own session launch plus hook registration; clawhip stays the routing,
  118. normalization, and delivery layer.
  119. Shared v1 hook events:
  120. - `SessionStart`
  121. - `PreToolUse`
  122. - `PostToolUse`
  123. - `UserPromptSubmit`
  124. - `Stop`
  125. Local ingress for sample payloads and manual verification:
  126. ```bash
  127. clawhip native hook --provider codex --file payload.json
  128. clawhip native hook --provider claude --file payload.json
  129. cat payload.json | clawhip native hook --provider codex
  130. ```
  131. Recommended installation model:
  132. - install the shared clawhip bridge in `~/.clawhip/hooks/native-hook.mjs`
  133. - for Codex, align with the official hook contract: use either `~/.codex/hooks.json` or `<repo>/.codex/hooks.json`
  134. - for Claude Code, install the provider-native hook config globally in `~/.claude/settings.json`
  135. - keep provider config in the provider-owned config files
  136. - keep routing metadata in `.clawhip/project.json`
  137. - use `.clawhip/hooks/` only for additive augmentation such as frontmatter or recent context
  138. clawhip still pairs well with tmux when you want keyword/stale monitoring, but tmux is now
  139. optional and no longer the primary hook-registration surface.
  140. For tmux-backed recovery into an already-running hooked session, use:
  141. ```bash
  142. clawhip deliver --session <tmux-session> --prompt "..." --max-enters 4
  143. ```
  144. `clawhip deliver` validates repo-local prompt-submit hook setup, confirms the target pane is an
  145. active Codex/Claude (including OMC/OMX wrapper) session, then retries Enter until
  146. `.clawhip/state/prompt-submit.json` changes or the bounded retry limit is reached.
  147. ## Filesystem-offloaded memory pattern
  148. 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/`.
  149. Use this when you want:
  150. - a small, fast memory surface for agents
  151. - durable project/channel/daily memory in files
  152. - explicit read/write routing instead of one giant note
  153. - ongoing memory refactoring as part of operations
  154. Start here:
  155. - [docs/memory-offload-architecture.md](docs/memory-offload-architecture.md)
  156. - [docs/memory-offload-guide.md](docs/memory-offload-guide.md)
  157. - [docs/examples/MEMORY.example.md](docs/examples/MEMORY.example.md)
  158. - [skills/memory-offload/SKILL.md](skills/memory-offload/SKILL.md)
  159. Runtime support now includes a small bootstrap/inspection surface:
  160. ```bash
  161. # create a scaffold in the current repo
  162. clawhip memory init --project clawhip --channel discord-alerts --agent codex
  163. # inspect whether the expected files and directories exist
  164. clawhip memory status --project clawhip --channel discord-alerts --agent codex
  165. ```
  166. `clawhip memory init` creates `MEMORY.md`, `memory/README.md`, a daily shard, a project shard,
  167. topic files, and optional channel/agent shards without overwriting existing files unless you pass
  168. `--force`.
  169. ## Plugin architecture
  170. clawhip now includes a simple `plugins/` directory for tool-specific shell bridges.
  171. Each plugin lives in its own subdirectory with:
  172. - `plugin.toml` for lightweight metadata
  173. - `bridge.sh` for shell hook entrypoints
  174. Built-in starter plugins:
  175. - `plugins/codex/`
  176. - `plugins/claude-code/`
  177. List installed plugins with:
  178. ```bash
  179. clawhip plugin list
  180. ```
  181. ## Description
  182. Operational spec for OpenClaw / Clawdbot agents consuming this repo.
  183. Repo role:
  184. - executable/runtime repo
  185. - daemon-first Discord notification gateway
  186. - typed event routing runtime
  187. - extracted Git/GitHub/tmux source monitors
  188. - multi-delivery router with renderer/sink separation
  189. - lifecycle surface: install / update / uninstall / start / status
  190. Attachment model:
  191. - repo = runtime
  192. - `SKILL.md` = attach/install/usage instructions for OpenClaw / Clawdbot
  193. - README = agent-facing operational spec
  194. Default daemon endpoint:
  195. - `http://127.0.0.1:25294`
  196. ## OpenClaw install contract
  197. Primary install entrypoint:
  198. ```text
  199. @openclaw install <repo_url>
  200. ```
  201. Expected downstream automation behavior:
  202. 1. clone repo
  203. 2. run `./install.sh`
  204. 3. read `SKILL.md`
  205. 4. attach skill
  206. 5. scaffold config / presets
  207. 6. start daemon
  208. 7. run live verification
  209. Reference repo URL:
  210. ```text
  211. https://github.com/Yeachan-Heo/clawhip
  212. ```
  213. ## Discord bot setup
  214. > **Recommended:** Create a dedicated Discord bot for clawhip. Do not reuse your Clawdbot / OpenClaw bot token.
  215. 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.
  216. 1. Create a new bot at [Discord Developer Portal](https://discord.com/developers/applications) (e.g. "CCNotifier")
  217. 2. Copy the bot token
  218. 3. Invite to your server with **Send Messages** permission
  219. 4. Set the token in config:
  220. ```toml
  221. [providers.discord]
  222. token = "your-dedicated-clawhip-bot-token"
  223. default_channel = "your-default-channel-id"
  224. [dispatch]
  225. routine_batch_window_secs = 5
  226. ci_batch_window_secs = 300
  227. ```
  228. Legacy `[discord]` config is still accepted and normalized at load time.
  229. `[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.
  230. `[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.
  231. ## Discord webhook setup
  232. Webhook mode works without a bot token.
  233. Quick start:
  234. ```bash
  235. clawhip setup --webhook "https://discord.com/api/webhooks/..."
  236. ```
  237. Bounded setup presets also support:
  238. ```bash
  239. clawhip setup \
  240. --bot-token "discord-bot-token" \
  241. --default-channel "1234567890" \
  242. --default-format alert \
  243. --daemon-base-url "http://127.0.0.1:25294"
  244. ```
  245. `clawhip setup` stays non-interactive and intentionally limited to the supported presets:
  246. - Discord webhook quickstart route
  247. - Discord bot token
  248. - Default channel
  249. - Default message format
  250. - Daemon base URL
  251. - Official GJC question subscription and repository-scoped route (channel, mention, fallback)
  252. To opt into the official GJC question bridge from a repository checkout, provide a destination channel (or explicitly reuse the configured default channel):
  253. ```bash
  254. clawhip setup \
  255. --question-channel "QUESTIONS_CHANNEL_ID" \
  256. --question-mention "<@OPERATOR_ID>"
  257. # Equivalent fallback form when [defaults].channel is already configured.
  258. clawhip setup --question-fallback
  259. ```
  260. This setup path converges the setup-owned `gjc-question` websocket subscription and one
  261. `workflow.question` route filtered by the current repository identity. It never edits an
  262. existing `workflow.gate` route. Re-running setup updates those same named entries instead of
  263. duplicating them. Question setup only owns the destination channel, optional mention, and
  264. fallback-to-default choice; the subscription endpoint remains `GJC_QUESTION_WS` and is read
  265. only by the daemon environment.
  266. Route example:
  267. ```toml
  268. [[routes]]
  269. event = "tmux.keyword"
  270. sink = "discord"
  271. webhook = "https://discord.com/api/webhooks/..."
  272. ```
  273. ## Slack webhook setup
  274. Slack webhook routes work without a bot token.
  275. 1. In Slack, open the app settings for your workspace and enable **Incoming Webhooks**
  276. 2. Add a new webhook to the channel you want clawhip to notify
  277. 3. Copy the generated `https://hooks.slack.com/services/...` URL into a route
  278. Route examples:
  279. ```toml
  280. [[routes]]
  281. event = "git.commit"
  282. filter = { repo = "my-app" }
  283. slack_webhook = "https://hooks.slack.com/services/T.../B.../xxx"
  284. format = "compact"
  285. [[routes]]
  286. event = "tmux.keyword"
  287. sink = "slack"
  288. webhook = "https://hooks.slack.com/services/T.../B.../yyy"
  289. format = "alert"
  290. ```
  291. ## Signed HTTP webhook setup
  292. The generic `http` sink delivers a normalized, bounded, public-safe JSON event directly to a
  293. local controller such as Hermes. Discord is optional when every event you intend to deliver is
  294. covered by HTTP, Slack, local-file, or Discord-webhook routes.
  295. Keep the HMAC secret outside the TOML file and reference its environment-variable name:
  296. ```bash
  297. export HERMES_CLAWHIP_HMAC_SECRET="replace-with-a-random-shared-secret"
  298. ```
  299. ```toml
  300. [providers.http]
  301. endpoint = "http://127.0.0.1:8644/webhooks/clawhip-controller"
  302. hmac_secret_env = "HERMES_CLAWHIP_HMAC_SECRET"
  303. [[routes]]
  304. event = "*"
  305. sink = "http"
  306. ```
  307. The sink signs the exact transmitted bytes with HMAC-SHA256 and sends the result as
  308. `X-Hub-Signature-256: sha256=<hex>`. `X-Request-ID` is stable for the normalized event and is
  309. also present in the body. Plain HTTP is accepted only for loopback endpoints (`127.0.0.0/8`,
  310. `::1`, or `localhost`); non-loopback endpoints must use HTTPS. Redirects are disabled, response
  311. bodies and endpoint paths are not copied into errors or telemetry, and raw event payloads,
  312. credentials, local paths, and webhook URLs are excluded or redacted from the outbound body.
  313. HTTP and Discord can fan out from the same event by adding a second matching route:
  314. ```toml
  315. [[routes]]
  316. event = "github.*"
  317. sink = "http"
  318. [[routes]]
  319. event = "github.*"
  320. sink = "discord"
  321. channel = "PROJECT_CHANNEL_ID"
  322. ```
  323. ## System model
  324. ```text
  325. [CLI / webhook / git / GitHub / tmux]
  326. -> [sources]
  327. -> [mpsc queue]
  328. -> [dispatcher]
  329. -> [router -> renderer -> Discord/Slack/HTTP sink]
  330. -> [Discord REST / Slack webhook / signed HTTP delivery]
  331. ```
  332. Input sources in v0.3.0:
  333. - CLI thin clients and custom events
  334. - GitHub webhook ingress plus GitHub polling source
  335. - git monitor source
  336. - tmux monitor source
  337. - `clawhip tmux new` / `clawhip tmux watch` registration path
  338. ### GitHub webhook authentication
  339. Configure a GitHub webhook to POST JSON to the daemon's `/github` endpoint.
  340. Set the same secret in GitHub's webhook settings and in the daemon's environment:
  341. ```toml
  342. [providers.github]
  343. webhook_secret_env = "CLAWHIP_GITHUB_WEBHOOK_SECRET"
  344. [daemon]
  345. bind_host = "127.0.0.1"
  346. ```
  347. The config stores only the environment variable name, not the secret. When
  348. configured, **all** `/github` events require a valid `X-Hub-Signature-256`
  349. HMAC-SHA256 signature over the exact raw request body. Missing/invalid signatures
  350. or a missing/empty secret environment variable return `401` without emitting an
  351. event. JSON parsing and event handling happen only after verification.
  352. With no secret configured, existing `issues.opened`, release
  353. (`published`/`released`/`prereleased`/`edited`), and `pull_request.opened`/`closed`
  354. webhooks retain their unauthenticated behavior. The following activity events
  355. require a configured secret and valid signature. With no secret configured they
  356. are ignored with `202` to avoid introducing a new unauthenticated notification
  357. injection surface (with a configured secret, invalid/missing signatures get `401`):
  358. | GitHub event/action | Emitted kind |
  359. | --- | --- |
  360. | `issue_comment.created` on an issue | `github.issue-commented` |
  361. | `issue_comment.created` on a PR | `github.pr-commented` |
  362. | `pull_request_review.submitted` | `github.pr-reviewed` (approved, changes_requested, commented only) |
  363. | `pull_request_review_comment.created` | `github.pr-review-commented` |
  364. Edited/deleted comments and other review states/actions are ignored. Activity
  365. payloads contain identifiers and metadata, never comment/review bodies. Webhooks
  366. are independent of polling monitor flags, including `emit_pr_activity`.
  367. For authenticated requests with `X-GitHub-Delivery`, the daemon remembers the last
  368. 1,000 successful delivery IDs in memory (FIFO). Redeliveries return `202` without
  369. emitting again. IDs are not persisted across restarts; requests without a delivery
  370. ID are not deduplicated. Failed requests remain retryable. Enabling both webhook
  371. activity and `emit_pr_activity` polling for the same repo can produce duplicate
  372. notifications across those sources; consumers can dedupe PR activity using
  373. `comment_id`/`review_id`.
  374. The default bind address is `0.0.0.0`. Prefer `bind_host = "127.0.0.1"` with a
  375. reverse proxy exposing only `/github` over HTTPS. The webhook secret protects
  376. `/github`, not other daemon endpoints; do not expose the whole daemon publicly.
  377. ## Input -> behavior -> verification
  378. ### 1. Custom client event
  379. Input:
  380. ```bash
  381. clawhip send --channel <id> --message "text"
  382. ```
  383. Behavior:
  384. - POST to daemon `/api/event`
  385. - daemon routes event
  386. - Discord message emitted
  387. Verification:
  388. - `clawhip status`
  389. - inspect configured Discord channel for rendered payload
  390. ### 2. GitHub issue preset family
  391. Input:
  392. - GitHub webhook `issues.opened`
  393. - built-in GitHub issue monitor detection
  394. - CLI thin client `clawhip github issue-opened ...`
  395. Behavior:
  396. - emit `github.issue-opened`
  397. - route via `github.*`
  398. - apply repo filter
  399. - prepend route mention if configured
  400. - send to Discord
  401. Verification:
  402. - create real issue
  403. - confirm final Discord body contains:
  404. - repo
  405. - issue number
  406. - title
  407. - mention when configured
  408. ### 3. GitHub issue commented preset
  409. Input:
  410. - authenticated GitHub webhook `issue_comment.created` on an issue (see webhook authentication above)
  411. - built-in GitHub issue monitor comment delta
  412. Behavior:
  413. - emit `github.issue-commented`
  414. - route via `github.*`
  415. - apply repo filter
  416. - prepend route mention if configured
  417. Verification:
  418. - add real issue comment
  419. - confirm final Discord message body in target channel
  420. ### 4. GitHub issue closed preset
  421. Input:
  422. - built-in GitHub issue monitor state transition
  423. Behavior:
  424. - emit `github.issue-closed`
  425. - route via `github.*`
  426. - apply repo filter
  427. - prepend route mention if configured
  428. Verification:
  429. - close real issue
  430. - confirm final Discord message body in target channel
  431. ### 5. GitHub PR preset family
  432. Input:
  433. - GitHub webhook `pull_request.opened` / `pull_request.closed`
  434. - built-in PR monitor state changes
  435. - CLI thin client `clawhip github pr-status-changed ...`
  436. Behavior:
  437. - emit `github.pr-status-changed`
  438. - route via `github.*`
  439. - apply repo filter
  440. - prepend route mention if configured
  441. Verification:
  442. - open real PR
  443. - merge / close PR
  444. - confirm final Discord message body in target channel
  445. ### 6. Git commit preset family
  446. Input:
  447. - built-in git monitor polling local repo
  448. - CLI thin client `clawhip git commit ...`
  449. Behavior:
  450. - emit `git.commit`
  451. - route through git/github family matching
  452. - preserve repo-based route filtering
  453. - prepend route mention if configured
  454. Verification:
  455. - create real empty commit in monitored repo
  456. - confirm final Discord body contains commit summary and mention
  457. ### 7. Provider-native session contract
  458. Canonical native routing now starts from provider-native Codex and Claude hook payloads and
  459. enters clawhip through `clawhip native hook`.
  460. Shared v1 hook events:
  461. - `SessionStart`
  462. - `PreToolUse`
  463. - `PostToolUse`
  464. - `UserPromptSubmit`
  465. - `Stop`
  466. Stable routing metadata (when available):
  467. - `provider`
  468. - `event`
  469. - `session_id`
  470. - `directory`
  471. - `worktree_path`
  472. - `repo_name`
  473. - `project`
  474. - `branch`
  475. - `tool_name`
  476. - `command`
  477. - `summary`
  478. - `event_timestamp`
  479. Augmentation rules:
  480. - provider input + clawhip project metadata define the immutable base contract
  481. - `.clawhip/hooks/` scripts may only add fields or enrich message/context
  482. - augmenters must not remove or overwrite base routing keys
  483. Route guidance:
  484. - prefer filters like `provider`, `event`, `repo_name`, `project`, and `branch`
  485. - avoid route logic that depends on rendered message text
  486. - keep provider-specific extras out of the shared v1 route surface until explicitly adopted
  487. See [`docs/native-event-contract.md`](docs/native-event-contract.md) for the routing/augmentation
  488. guide and [`docs/event-contract-v1.md`](docs/event-contract-v1.md) for the frozen shared-event
  489. reference.
  490. ### 8. Agent lifecycle preset family
  491. Input:
  492. ```bash
  493. clawhip agent started --name worker-1 --session sess-123 --project my-repo
  494. clawhip agent blocked --name worker-1 --summary "waiting for review"
  495. clawhip agent finished --name worker-1 --elapsed 300 --summary "PR created"
  496. clawhip agent failed --name worker-1 --error "build failed"
  497. ```
  498. Behavior:
  499. - emit `agent.started`, `agent.blocked`, `agent.finished`, or `agent.failed`
  500. - route via `agent.*`
  501. - apply optional project/session filters
  502. - include status / elapsed / summary / error details in rendered messages
  503. - prepend route mention if configured
  504. Verification:
  505. - send each CLI event against a running daemon
  506. - confirm final Discord body contains agent name and lifecycle state
  507. - confirm `agent.*` route rules match each event type
  508. ### 9. tmux keyword preset
  509. Input:
  510. - built-in tmux monitor detects configured keyword
  511. - CLI thin client `clawhip tmux keyword ...`
  512. Behavior:
  513. - emit `tmux.keyword`
  514. - route via `tmux.*`
  515. - prepend route mention if configured
  516. Verification:
  517. - print configured keyword in real monitored tmux session
  518. - confirm final Discord body in target channel
  519. ### 10. tmux stale preset
  520. Input:
  521. - built-in tmux stale detection
  522. - CLI thin client `clawhip tmux stale ...`
  523. Behavior:
  524. - emit `tmux.stale`
  525. - route via `tmux.*`
  526. - prepend route mention if configured
  527. Verification:
  528. - let real tmux session idle past threshold
  529. - confirm final Discord body in target channel
  530. ### 11. Provider-native sessions + tmux fallback
  531. Preferred input:
  532. ```bash
  533. clawhip native hook --provider codex --file payload.json
  534. clawhip native hook --provider claude --file payload.json
  535. clawhip tmux list
  536. ```
  537. Fallback/debug input:
  538. ```bash
  539. clawhip tmux new -s <session> \
  540. --mention '<@id>' \
  541. --keywords 'error,PR created,FAILED,complete' \
  542. --stale-minutes 10 \
  543. --format alert \
  544. --retry-enter true \
  545. --retry-enter-count 4 \
  546. --retry-enter-delay-ms 250 \
  547. --shell /bin/zsh \
  548. -- command args
  549. clawhip tmux watch -s <existing-session> \
  550. --mention '<@id>' \
  551. --keywords 'error,PR created,FAILED,complete' \
  552. --stale-minutes 10 \
  553. --format alert \
  554. --retry-enter true
  555. clawhip deliver \
  556. --session <existing-session> \
  557. --prompt "continue from the latest blocker and open a PR to dev" \
  558. --max-enters 4
  559. ```
  560. Behavior:
  561. - Codex and Claude should own session launch and hook registration
  562. - `clawhip native hook` is the local thin-client ingress for provider payloads
  563. - `tmux new` / `tmux watch` are fallback paths for debugging or manual recovery
  564. - `deliver` is the prompt recovery path for an already-running hooked tmux-backed provider session
  565. - `tmux list` shows active daemon-known watches with source, registration timestamp, and parent-process info
  566. - final delivery still goes through daemon routing
  567. - `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)
  568. Routing note:
  569. - session names are labels for operators, not routing authority
  570. - project metadata should be the source of truth for routing
  571. - broad prefix monitors like `clawhip*` are dangerous because they can overlap with launcher-registered watches and create stale/keyword noise
  572. Verification:
  573. - launch a real Codex or Claude session with provider-native hooks enabled
  574. - verify the tmux pane is actually alive
  575. - confirm routed delivery in Discord
  576. - if alert text conflicts with pane reality, trust the pane and inspect monitor registrations
  577. ### 12. install lifecycle preset
  578. Input:
  579. ```bash
  580. ./install.sh
  581. clawhip install
  582. clawhip update --restart
  583. clawhip uninstall --remove-systemd --remove-config
  584. ```
  585. Behavior:
  586. - install binary from git clone
  587. - ensure config dir exists
  588. - optional systemd install
  589. - optional post-install GitHub star prompt on interactive local installs
  590. - update rebuilds/reinstalls and optionally restarts daemon
  591. - uninstall removes runtime artifacts
  592. Verification:
  593. - `clawhip --help`
  594. - `clawhip status`
  595. - `systemctl status clawhip` when systemd-enabled
  596. ## GitHub pull request activity (opt-in)
  597. Enable all three activity events on a Git repository monitor:
  598. ```toml
  599. [[monitors.git.repos]]
  600. path = "/path/to/repo"
  601. github_repo = "owner/repo"
  602. emit_pr_activity = true
  603. ```
  604. `emit_pr_activity` defaults to `false`, including for existing configurations.
  605. It is independent of `emit_pr_status` and `emit_issue_opened`. When disabled,
  606. the poller makes no additional requests and continues to ignore PR conversation comments.
  607. Route these events with `github.*` or their individual kinds:
  608. | Event | Activity | Extra payload fields |
  609. | --- | --- | --- |
  610. | `github.pr-commented` | PR conversation comment | `comment_id` |
  611. | `github.pr-review-commented` | Inline review comment | `comment_id`, `path` |
  612. | `github.pr-reviewed` | Submitted review | `review_id`, `state` (`approved`, `changes_requested`, `commented`) |
  613. All three payloads include `repo`, `number`, `title`, `author`, `pr_author`, and
  614. `url` (the comment/review permalink). For comments outside the current PR window
  615. or review scan, the poller resolves the title and PR author with
  616. `GET /repos/{owner}/{repo}/pulls/{number}`. A 256-entry in-memory FIFO cache avoids
  617. repeated lookups; window data takes precedence and refreshes cached titles.
  618. Unknown metadata goes into a shared in-memory FIFO of at most 500 pending
  619. comments (identifiers, author login, URL, timestamps and inline path, never body
  620. text). Pending IDs immediately enter their feed's deduplication FIFO. Each poll
  621. retries pending work oldest-first before reading new comments; remaining lookup
  622. budget can resolve newly queued work after both feeds are read. A 404 or 410 is
  623. cached as unavailable and emits with empty `title`/`pr_author` (until cache
  624. eviction or restart). Other failures, including missing PR authors, retry for at
  625. most 10 attempts before emitting empty metadata and reporting degraded operation.
  626. 403/429 use shared rate-limit backoff without consuming an attempt. Queue overflow
  627. emits the oldest unresolved comment rather than dropping it. Overflow and
  628. attempt-cap emissions carry empty `title`/`pr_author`, so routes filtering on
  629. `pr_author` do not match them; routing falls back according to route configuration.
  630. Overflow, give-up and budget deferral report throttled source degradation.
  631. The pending queue is in-memory: a restart drops unresolved queued comments.
  632. `pr_author` can be used in route payload filters to select your PRs. Comment and
  633. review **body text is never included** in these public-safe event payloads.
  634. Pending and dismissed reviews are not emitted, nor are edits to old comments.
  635. API cost per poll: conversation comments use an activity-owned repository
  636. `/issues/comments` feed; inline comments use the repository `/pulls/comments` feed
  637. (each up to 10 pages, 100 items/page), independent of the PR list so older PRs are
  638. still detected. The conversation feed adds one request per poll when unpaginated;
  639. pending metadata cache misses add at most 20 PR-detail requests per poll, one per
  640. distinct PR, shared by both comment feeds. Cold baselines never enqueue or look
  641. up seeded comments. The queue and cache survive CI-baseline persistence failures
  642. in the running process, but are not persisted across restarts.
  643. The conversation feed ignores issue comments and does not change the existing issue-comment count-delta
  644. poller or enable issue polling when disabled. PR conversation IDs have their own bounded deduplication FIFO;
  645. issue-comment churn or a CI-baseline persistence failure does not replay them.
  646. Cold start itself emits no activity and does not traverse full history. Conversation and inline
  647. comments read only the newest page (`sort=updated&direction=desc`) and seed all
  648. received PR-comment IDs. Reviews read only the newest PR page and seed reviews on PRs sharing
  649. that page's newest `updated_at`; more than 20 such PRs span polls without emission.
  650. Each cold fetch's server `Date` establishes its creation/submission eligibility
  651. lower bound L, falling back to the newest observed update when Date is missing or
  652. invalid. Later notifications require `created_at` / `submitted_at` >= L and an
  653. unseen ID, so unseen historical boundary items older than that cutoff do not replay.
  654. Timestamps have second precision: unseen historical items in the cutoff second
  655. cannot be distinguished from new same-second activity, especially with the fallback.
  656. After baseline, each comment feed uses its own updated-at pagination position P
  657. with ascending updates and `since=P-1s`. The 10-page cap reports source degradation
  658. and advances P to the last received update, but holds creation eligibility L fixed
  659. until the backlog drains. Thus a newly created comment edited before its first
  660. delivery is still eligible even when its creation precedes P. A completed fetch
  661. advances L to the maximum consumed update (never backwards); all updates through
  662. that position have been consumed. A failed fetch preserves both P and L. Only
  663. delivered, queued or deliberately seeded cold IDs enter the deduplication FIFO.
  664. Metadata availability never stops a feed or freezes P/L: pending comments retain
  665. their original eligibility independently of later feed positions. Both comment
  666. kinds share one pending FIFO, so new conversation comments cannot starve older
  667. inline comments of lookup budget. All requests remain subject to the shared
  668. GitHub rate-limit backoff.
  669. Reviews build a separate updated-desc PR window (up to 5 pages, 500 PRs), stopping
  670. only below the committed submission watermark. Boundary-second PRs are always
  671. rechecked; review IDs prevent duplicate notifications. A scan stores its fixed
  672. submission lower bound and pending PRs, fetching at most 20 PRs per poll (up to
  673. 10 pages of reviews per PR), oldest update first. No PR-list request is needed
  674. while that scan drains. The watermark advances to the window's newest PR update
  675. only when every pending PR succeeds; an individual failure or review-page cap
  676. reports throttled source degradation, requeues that PR, and retains the watermark.
  677. Thus reviews submitted before a PR's later update are not lost across scan polls.
  678. If more than 500 PRs have updated since the watermark, the PR-list cap still
  679. processes the newest 500-PR window and commits its upper bound on completion.
  680. It explicitly reports source degradation: **reviews on PRs outside that window
  681. may be lost**, rather than allowing a permanent backlog to starve progress.
  682. Pagination is not a transactional snapshot. Deduplication is in-memory and
  683. bounded to 1,000 IDs per activity kind; overlapping windows larger than that
  684. cache can replay IDs. Exactly 1,000 updates in either comment feed at the inclusive cursor second
  685. can fill every resumable window and block any later comment (as can larger ties).
  686. The conversation feed shares GitHub's `/issues/comments` endpoint with issue
  687. comments: filtering issue comments does not remove their pagination cost, so they
  688. occupy the same page slots and 10-page budget. A burst of issue comments can delay
  689. PR conversation notifications, and 1,000 issue comments tied at the cursor second
  690. can stall them as above.
  691. A PR with over 1,000 reviews can keep its
  692. scan waiting at the per-PR page cap. Restarting establishes fresh baselines.
  693. ## GitHub notifications (opt-in, across all repositories)
  694. Poll the authenticated user's notification inbox without configuring repositories
  695. or fetching PR metadata. This complements, rather than replaces, `emit_pr_activity`.
  696. Only activity GitHub places in your notification inbox is observed (including
  697. your PRs/issues, mentions and review requests); it is not a repository-wide audit log.
  698. ```toml
  699. [monitors.github_notifications]
  700. enabled = true # default false: zero requests when disabled
  701. poll_interval_secs = 60 # min 1; max(configured, latest valid X-Poll-Interval)
  702. participating = false # true sends participating=true
  703. reasons = [] # empty = all; e.g. ["author", "mention", "review_requested"]
  704. repos = [] # empty = all; e.g. ["owner/repo"]
  705. # channel = "CHANNEL_ID" # optional direct destination
  706. # channel_name = "development"
  707. # mention = "<@USER_ID>"
  708. format = "compact"
  709. [[routes]]
  710. event = "github.notification"
  711. filter = { reason = "review_requested", subject_type = "PullRequest" }
  712. channel = "REVIEW_CHANNEL_ID"
  713. ```
  714. Credentials use `CLAWHIP_GITHUB_TOKEN`, then `monitors.github_token`, then
  715. `gh auth token`. GitHub's [notifications REST documentation](https://docs.github.com/en/rest/activity/notifications)
  716. currently documents personal access tokens **(classic)** with `notifications` or
  717. `repo` scope; this endpoint does **not** support fine-grained personal access tokens.
  718. Authenticate `gh` with a credential that can read notifications.
  719. Each poll constructs at most five `GET /notifications` requests, with `all=true`,
  720. `participating` as configured, and `per_page=50`. Read threads are included, so
  721. an update read elsewhere before the next poll is still delivered once; delivery
  722. depends on the watermark and thread dedup, never on GitHub's unread flag. Constructed polling/pagination
  723. requests stay on the configured API origin; HTTP 3xx redirects retain the shared
  724. GitHub client's default behavior and can add transport requests or change origin.
  725. The committed watermark W advances only to the greatest `updated_at` actually
  726. received in a completed scan, never from the response `Date` or an incomplete
  727. fresh head page. Empty/older responses leave W unchanged; before any update has
  728. been covered, W is unset and requests omit `since`. Normal polls request
  729. `since=W-5m`. This fixed reconciliation overlap tolerates response generation
  730. latency, visibility lag and clock disagreement totaling less than five minutes;
  731. updates arriving behind that window are not guaranteed to be observed. Repeated
  732. updates are deduplicated by thread ID and `updated_at`. Conditional requests use
  733. `If-Modified-Since` no later than either the previous complete response's
  734. `Last-Modified` or W minus five minutes (the cold-start cutoff minus five minutes
  735. when W is unset), so a later response header cannot hide the overlap.
  736. An authenticated `304 Not Modified` emits nothing and does not consume the
  737. primary rate limit. In steady state these conditional savings are mostly
  738. unavailable: the conditional time is clamped to W minus five minutes, usually
  739. earlier than the inbox's last modification, so GitHub returns `200`. A `200`
  740. consumes the primary rate limit; at the default 60-second interval, one to five
  741. requests per poll is roughly 60–300 requests/hour of the authenticated
  742. 5,000/hour budget. Conditional times use the UTC IMF-fixdate HTTP-date format.
  743. The effective interval is
  744. the maximum of the configured interval and the **latest valid** `X-Poll-Interval`,
  745. including headers on failures and 304 responses; a later lower value reduces the
  746. delay again. Missing/invalid interval headers retain the latest valid value.
  747. Shared GitHub 403/429 backoff also applies.
  748. A five-page cap reports throttled source degradation and saves a catch-up window
  749. without advancing W. A catch-up that starts before W is set (for example, read
  750. history exceeding five pages on the cold poll) uses the cold-start cutoff in
  751. place of W, because older updates are never delivered; the baseline does not
  752. drain the whole read history. Outside a pinned tie, every catch-up poll first fetches one
  753. fresh head page with `since=<W at catch-up start>-5m`, so its newest 50 updates are not delayed
  754. by the backlog. The remaining four requests drain that same lower bound with
  755. `before=<oldest received updated_at + 1s>`. The head and backlog windows overlap,
  756. with no timestamp gap. Normal continuation uses only timestamps, restarting
  757. pagination at page one each poll; reading/updating earlier threads cannot shift
  758. a saved page offset past unseen older threads. Local reason/repo filters never
  759. advance or truncate the scan. Once the backlog is proven complete, W advances
  760. to the greatest update covered by that scan, excluding the incomplete head.
  761. The next normal scan therefore includes head overflow. Conditional requests are
  762. disabled throughout catch-up and on that first normal scan.
  763. HTTP/decoding failures and missing/invalid first-page Date headers preserve the
  764. watermark, continuation, thread baseline, and conditional cursor.
  765. **Oversized boundary-second limitation:** if more than 200 threads share
  766. the boundary `updated_at` second, they cannot all be reconciled in the four
  767. backlog requests. Bounded page offsets enumerate only that second, then restart
  768. at page one when they reach its end. Such cross-poll offsets never prove
  769. completion: contractions can skip an ID during one pass, but subsequent passes
  770. revisit it once the inbox stabilizes. W remains pinned and older backlog waits
  771. until a page-one scan proves the entire boundary second fits in one poll. The
  772. available tie budget determines how many pages that proof can cover.
  773. While pinned at second T, newer delivery has its own timestamp-only scan of
  774. `(T, now]`, using exclusive `since=T`. Every poll first fetches page one of this
  775. fresh head, even with a saved newer cursor. Up to three following requests go
  776. to newer-range pagination, leaving **at least one request for enumerating T**;
  777. unused newer requests go to T. An empty newer head leaves four tie pages only
  778. when no newer continuation is saved; an empty stale continuation costs one
  779. request, is then cleared, and leaves three tie pages. A
  780. newer scan starting afresh reuses the head as its first page. If it does not
  781. finish, it saves `before=<oldest received updated_at + 1s>` and restarts at page
  782. one of that timestamp window next poll, deduplicating the overlap by thread ID
  783. and `updated_at`. If a continuation exhausts its budget without moving `before`
  784. strictly older than its starting value, that stalled cursor is cleared so the
  785. next poll restarts from the fresh head. On completion it also restarts fresh
  786. next poll. This delivery scan
  787. never advances W or proves tie coverage. Thus, once the inbox stabilizes, a
  788. newer range with distinct timestamps drains across polls while T also receives
  789. enumeration requests; fresh head overflow cannot wait forever behind T.
  790. **Nested newer-tie limitation:** this newer-range delivery scan does not
  791. recursively enumerate oversized same-second groups. A group of more than 200
  792. newer threads at one second cannot fit its restarting budget (head plus three
  793. pages); a saved continuation has only three pages, so even a group of more than
  794. 150 threads at its boundary can stall it. Restarting a stalled cursor prevents
  795. distinct-timestamp arrivals above that group from being stranded between the
  796. head and the saved boundary: once the inbox freezes, each continuation either
  797. moves older or restarts a head-based scan. In the 201-thread nested-group case,
  798. 51 distinct arrivals above it all arrive within two successful polls (one to
  799. clear the stalled cursor, then one head-based scan to reach the 51st arrival).
  800. Unseen threads inside or below the oversized nested second can still wait
  801. indefinitely until the group shrinks; restarting does not enumerate that group
  802. recursively or prove its coverage. The fresh head and the original T enumeration
  803. still run, with W conservatively pinned.
  804. Avoiding recursive cursor trees keeps state and request allocation bounded;
  805. this is a delivery limitation, not a claim of complete coverage.
  806. Pinned ties can persist indefinitely and cost up to five constructed requests
  807. per poll, with throttled degradation reporting rather than unbounded requests.
  808. Even without oversized ties, more than 250 threads in the five-minute overlap
  809. can repeatedly trigger catch-up, at the same per-poll request bound.
  810. **Unread only; never marks read.** No PATCH/PUT requests are made. Reading a
  811. notification on github.com removes it from the unread feed; further activity
  812. re-surfaces it with a newer `updated_at`. The first successful poll seeds a
  813. baseline without replaying history. Its server `Date` is the eligibility cutoff
  814. (missing/invalid Date defers initialization). Subsequent polls emit one
  815. `github.notification` per thread whose `updated_at` advances, not per comment.
  816. An unseen thread older than that cutoff never replays unless it changes.
  817. The in-memory dedupe FIFO holds 1,000 threads; eviction can replay a post-cutoff
  818. thread within the reconciliation overlap or a repeatedly scanned oversized tie.
  819. Restarting establishes a fresh, silent baseline. GitHub's inbox is not a snapshot:
  820. continuous mutation during requests can delay observation, and updates must
  821. remain unread/visible to be fetched. Separate changes to one thread with the same
  822. second-resolution `updated_at` cannot be distinguished.
  823. Payloads contain no comment/review bodies, token, or private credential metadata.
  824. Repository names and titles can still identify private repositories: route only
  825. to destinations authorized to see the authenticated user's inbox.
  826. | Field | Meaning |
  827. | --- | --- |
  828. | `repo` | `owner/repo` |
  829. | `thread_id` | GitHub notification thread ID (string) |
  830. | `reason` | GitHub reason, e.g. `author`, `comment`, `mention`, `review_requested`, `assign`, `state_change`, `team_mention`, `ci_activity` |
  831. | `subject_type` | GitHub type, e.g. `PullRequest`, `Issue`, `Discussion`, `Release`, `CheckSuite`, `Commit` |
  832. | `title` | Subject title, never its body |
  833. | `number` | Optional issue/PR/discussion number derived without another request |
  834. | `url` | Derived HTML URL, with a comment anchor when determinable; otherwise repository URL |
  835. | `updated_at` | GitHub thread update timestamp |
  836. ## Preset event families
  837. ### GitHub family
  838. - `github.notification`
  839. - `github.issue-opened`
  840. - `github.issue-commented`
  841. - `github.issue-closed`
  842. - `github.pr-commented`
  843. - `github.pr-review-commented`
  844. - `github.pr-reviewed`
  845. - `github.pr-status-changed`
  846. ### Git family
  847. - `git.commit`
  848. - `git.branch-changed`
  849. ### Agent family
  850. - `agent.started`
  851. - `agent.blocked`
  852. - `agent.finished`
  853. - `agent.failed`
  854. ### Native session family
  855. - `session.started`
  856. - `session.blocked`
  857. - `session.finished`
  858. - `session.failed`
  859. - `session.retry-needed`
  860. - `session.pr-created`
  861. - `session.test-started`
  862. - `session.test-finished`
  863. - `session.test-failed`
  864. - `session.handoff-needed`
  865. ### tmux family
  866. - `tmux.keyword`
  867. - `tmux.stale`
  868. ## Route contract
  869. Config file:
  870. ```text
  871. ~/.clawhip/config.toml
  872. ```
  873. Route model:
  874. ```toml
  875. [[routes]]
  876. event = "github.*"
  877. filter = { repo = "clawhip" }
  878. sink = "discord"
  879. channel = "PROJECT_CHANNEL_ID"
  880. mention = "@maintainer-or-team"
  881. format = "compact"
  882. allow_dynamic_tokens = false
  883. [[routes]]
  884. event = "session.*"
  885. filter = { tool = "omx", repo_name = "clawhip" }
  886. sink = "discord"
  887. channel = "PROJECT_CHANNEL_ID"
  888. format = "compact"
  889. allow_dynamic_tokens = false
  890. [[routes]]
  891. event = "session.*"
  892. filter = { tool = "omx", repo_name = "clawhip", session_id = "sess-123" }
  893. sink = "discord"
  894. thread = "DISCORD_THREAD_ID"
  895. format = "compact"
  896. allow_dynamic_tokens = false
  897. [[routes]]
  898. event = "agent.*"
  899. filter = { project = "clawhip" }
  900. sink = "discord"
  901. channel = "PROJECT_CHANNEL_ID"
  902. format = "alert"
  903. allow_dynamic_tokens = false
  904. ```
  905. Resolution rules:
  906. 1. event family match
  907. 2. payload filter match
  908. 3. route sink / target / format / template / mention applied
  909. 4. default fallback used if route fields absent
  910. Discord thread targets:
  911. - Use `thread = "DISCORD_THREAD_ID"` on a Discord route to deliver directly into
  912. a thread. This is explicit; clawhip does not infer threads from `channel` IDs,
  913. names, session labels, or payload fields.
  914. - A Discord route may set exactly one delivery target: `channel`, `thread`, or
  915. `webhook`.
  916. - Thread delivery uses the configured thread ID as the Discord message target.
  917. If Discord reports the thread as archived, missing, forbidden, or otherwise
  918. unreachable, clawhip records a concise delivery error and does **not**
  919. automatically fall back to the parent channel.
  920. - Diagnostics and binding verification only reference configured IDs and status
  921. outcomes; clawhip does not list or dump private channel/thread inventories.
  922. ## Gateway allowlist diagnostics
  923. When clawhip sends through a local Clawdbot gateway, route channel IDs must also
  924. be present in the gateway's Discord allowlist. Check that boundary with:
  925. ```bash
  926. clawhip config verify-gateway-allowlist
  927. clawhip config verify-gateway-allowlist --gateway-config ~/.clawdbot/clawdbot.json
  928. clawhip config verify-gateway-allowlist --json
  929. ```
  930. The default gateway config path is `~/.clawdbot/clawdbot.json` when `HOME` is
  931. available; use `--gateway-config <path>` for any other local file. The command
  932. reads only `channels.discord.guilds[*].channels.<channel_id>.allow = true`,
  933. compares it with clawhip's configured Discord channel destinations, and exits
  934. non-zero when any destination is missing or not explicitly allowed.
  935. Output is public-safe by design: text and JSON reports include counts, clawhip
  936. source labels, and channel IDs only. They do not dump gateway tokens, webhook
  937. URLs, raw config payloads, or unrelated gateway fields. Discord/Slack webhooks, HTTP routes,
  938. localfile routes, and thread-only targets are outside this allowlist check.
  939. ## Dynamic token contract
  940. Only for routes with:
  941. ```toml
  942. allow_dynamic_tokens = true
  943. ```
  944. Supported tokens:
  945. - `{repo}`
  946. - `{number}`
  947. - `{title}`
  948. - `{session}`
  949. - `{keyword}`
  950. - `{sh:...}`
  951. - `{tmux_tail:session:lines}`
  952. - `{file_tail:/path:lines}`
  953. - `{env:NAME}`
  954. - `{now}`
  955. - `{iso_time}`
  956. Safety:
  957. - allowlisted token kinds only
  958. - route-level opt-in only
  959. - short timeout
  960. - output cap
  961. ## Install surface
  962. ### From crates.io
  963. ```bash
  964. cargo install clawhip
  965. ```
  966. Published at [crates.io/crates/clawhip](https://crates.io/crates/clawhip). Requires Rust toolchain.
  967. ### Prebuilt binary installer (recommended, no Rust needed)
  968. ```bash
  969. curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Yeachan-Heo/clawhip/releases/latest/download/clawhip-installer.sh | sh
  970. ```
  971. This installs the latest prebuilt `clawhip` binary from GitHub Releases into `$CARGO_HOME/bin` (typically `~/.cargo/bin`).
  972. 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`.
  973. ### Repo-local install
  974. ```bash
  975. ./install.sh
  976. ./install.sh --systemd
  977. ```
  978. `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.
  979. 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`.
  980. ### Runtime lifecycle commands
  981. ```bash
  982. clawhip install
  983. clawhip install --systemd
  984. clawhip install --skip-star-prompt
  985. clawhip update --restart
  986. clawhip uninstall
  987. clawhip uninstall --remove-systemd --remove-config
  988. ```
  989. `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`.
  990. ## systemd contract
  991. Unit file:
  992. ```text
  993. deploy/clawhip.service
  994. ```
  995. Expected install path:
  996. - copy to `/etc/systemd/system/clawhip.service`
  997. - `systemctl daemon-reload`
  998. - `systemctl enable --now clawhip`
  999. ## Deployed build identity
  1000. The crate version only changes on release, so `clawhip 0.6.11` cannot tell a
  1001. freshly deployed daemon apart from one still running a binary built several
  1002. merges earlier. Every build therefore stamps the source revision it was built
  1003. from, and both the CLI and the daemon report it:
  1004. ```bash
  1005. clawhip --version
  1006. # clawhip 0.6.11 (7bad9d24df18) built from that commit
  1007. # clawhip 0.6.11 (7bad9d24df18-dirty) build tree had uncommitted changes
  1008. # clawhip 0.6.11 revision unavailable (e.g. source tarball)
  1009. curl -s localhost:25294/health | jq .build
  1010. # { "version": "0.6.11", "commit": "7bad9d24df18...", "short_commit": "7bad9d24df18",
  1011. # "dirty": false, "commit_source": "git" }
  1012. ```
  1013. Compare `build.commit` against the revision you expect to have deployed to
  1014. confirm a rollout landed instead of inferring it from a green repository state.
  1015. When `[update].repo_root` is configured the daemon makes that comparison
  1016. itself — see [Deployment drift alerts](#deployment-drift-alerts).
  1017. `commit_source` is `git` for checkout builds, `environment` when a packaging
  1018. pipeline supplies `CLAWHIP_BUILD_COMMIT` (or CI supplies `GITHUB_SHA`), and
  1019. `unavailable` when no revision could be determined. Only the commit object
  1020. name, a dirty flag, and that source are exposed — no branches, paths, or
  1021. hostnames. A build without `git` or outside a checkout still succeeds.
  1022. ## Deployment drift alerts
  1023. Knowing the build revision only helps if somebody compares it. When
  1024. `[update].repo_root` points at the source checkout, the daemon does that
  1025. comparison itself every 5 minutes and alerts once per newly observed drift
  1026. pair:
  1027. ```
  1028. clawhip deployment drift: running binary was built from c4774562c6b0,
  1029. but the source checkout is at dd1494cc0f4d.
  1030. The running service is not the code in the checkout; rebuild and restart to deploy it.
  1031. ```
  1032. The alert is delivered like any other custom event (`[update].channel` selects
  1033. the target), and the latest observation is always readable:
  1034. ```bash
  1035. curl -s localhost:25294/health | jq .deployment
  1036. # { "state": "drift", "binary_commit": "c4774562...", "source_commit": "dd1494cc...", "reason": null }
  1037. ```
  1038. `state` is one of:
  1039. | state | meaning |
  1040. | --- | --- |
  1041. | `match` | the running binary was built from the checkout's current `HEAD` |
  1042. | `drift` | the binary was built from a different revision; **alerts** |
  1043. | `unknown` | not comparable; never alerts, and `reason` says why |
  1044. `unknown` is deliberate rather than a silent pass. It is reported when no
  1045. checkout is configured, when `HEAD` is unreadable (missing directory, not a
  1046. repository), when the binary carries no stamped revision (e.g. a crates.io or
  1047. tarball build), or when the binary was built from a modified tree — a `-dirty`
  1048. build provably is not exactly its commit, so it is never called a match.
  1049. Only commit object names are exposed; the checkout path never appears in an
  1050. event payload or on the health surface.
  1051. ## Live verification runbook
  1052. Use:
  1053. - `docs/live-verification.md`
  1054. - `scripts/live-verify-default-presets.sh`
  1055. - `scripts/internal-pr-format-gate.sh` for cheap local format gating before internal PR create/update flows
  1056. Required live sign-off presets:
  1057. - issue opened
  1058. - issue commented
  1059. - issue closed
  1060. - PR opened
  1061. - PR status changed
  1062. - PR merged
  1063. - git commit
  1064. - provider-native shared hook events
  1065. - tmux keyword
  1066. - tmux stale
  1067. - tmux wrapper
  1068. - tmux watch
  1069. - install/update/uninstall
  1070. ## Minimal operational commands
  1071. ```bash
  1072. clawhip # start daemon
  1073. clawhip --version # crate version + build revision of this binary
  1074. clawhip status # daemon health
  1075. clawhip config # bounded preset editor / config inspection
  1076. clawhip config verify-gateway-allowlist # check Clawdbot gateway allowlist coverage
  1077. clawhip send ... # thin client custom event
  1078. clawhip github ... # thin client GitHub event
  1079. clawhip git ... # thin client git event
  1080. clawhip agent ... # thin client agent lifecycle event
  1081. clawhip native hook ... # provider-native hook thin client
  1082. clawhip tmux ... # thin client / wrapper surface
  1083. clawhip plugin list # list installed/bundled shell-hook plugins
  1084. clawhip gajae status # check local GAJAE CLI bridge availability
  1085. ```
  1086. ## GAJAE CLI bridge
  1087. `clawhip gajae` provides a small Rust CLI bridge for local GAJAE dogfooding:
  1088. ```bash
  1089. clawhip gajae status
  1090. clawhip gajae profile install
  1091. clawhip gajae preflight
  1092. clawhip gajae doctor --repo owner/repo
  1093. clawhip gajae profile verify
  1094. ```
  1095. `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.
  1096. GAJAE route handlers are daemon-side and default off. Enable them explicitly and attach a bounded handler to an approved route:
  1097. ```toml
  1098. [gajae]
  1099. handlers_enabled = true
  1100. handler_timeout_ms = 5000
  1101. handler_max_output_bytes = 16384
  1102. [[routes]]
  1103. event = "github.pr-*"
  1104. filter = { repo = "clawhip" }
  1105. sink = "discord"
  1106. channel = "OPS_CHANNEL_ID"
  1107. gajae = { subcommand = "handle-event", args = ["--profile", "safe"] }
  1108. ```
  1109. 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.
  1110. ## Internal PR fast-path
  1111. Before opening or updating an internal PR from a Rust worktree, run:
  1112. ```bash
  1113. scripts/internal-pr-format-gate.sh
  1114. ```
  1115. If you already know the tree just needs formatting, auto-fix first:
  1116. ```bash
  1117. scripts/internal-pr-format-gate.sh --fix
  1118. ```
  1119. This catches the cheapest class of red CI (`cargo fmt` only) locally before PR create/update churn.
  1120. ## GEO visibility benchmark
  1121. 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.
  1122. - Spec: [`geobench/clawhip.yaml`](geobench/clawhip.yaml)
  1123. - Runbook: [`docs/geobench.md`](docs/geobench.md)
  1124. ## GitHub Actions platform status monitor
  1125. Poll the public GitHub Statuspage machine-readable API for GitHub Actions (and optionally other components) without using GitHub API tokens or websocket subscriptions.
  1126. This is a daemon monitor (`monitors.github_status`), **not** a `[[subscriptions]]` websocket worker. Keep it separate from GJC workflow-gate / question subscriptions.
  1127. Official public endpoints (no auth, no secrets):
  1128. - `https://www.githubstatus.com/api/v2/summary.json`
  1129. - `https://www.githubstatus.com/api/v2/status.json`
  1130. - `https://www.githubstatus.com/api/v2/components.json`
  1131. - `https://www.githubstatus.com/api/v2/incidents.json`
  1132. `status.github.com` serves the same Statuspage surface; clawhip defaults to the `www.githubstatus.com` API base.
  1133. ```toml
  1134. [monitors.github_status]
  1135. enabled = true
  1136. # Public Statuspage API; no token. Override only for tests/mirrors.
  1137. api_base = "https://www.githubstatus.com/api/v2"
  1138. components = ["Actions"]
  1139. poll_interval_secs = 60
  1140. # Optional direct channel; prefer an explicit route for gajae-code dev.
  1141. # channel = "YOUR_GAJAE_CODE_DEV_CHANNEL_ID"
  1142. # channel_name = "gajae-code-dev"
  1143. format = "alert"
  1144. [[routes]]
  1145. event = "github.actions-*"
  1146. sink = "discord"
  1147. channel = "YOUR_GAJAE_CODE_DEV_CHANNEL_ID"
  1148. channel_name = "gajae-code-dev"
  1149. format = "alert"
  1150. ```
  1151. Events:
  1152. - `github.actions-status` — watched component transitions among `degraded_performance`, `partial_outage`, `major_outage`, `under_maintenance`, and recovery to `operational`
  1153. - `github.actions-incident` — incident opened / update / resolved for incidents that affect a watched component
  1154. Anti-spam:
  1155. - first successful poll establishes a baseline and emits nothing
  1156. - stable component status and identical incident update IDs do not re-alert
  1157. - only lifecycle deltas (status change, new update id, resolve) emit
  1158. ## Websocket subscriptions
  1159. 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.
  1160. Set the endpoint only in the daemon environment, then keep the subscription policy and route ownership in `~/.clawhip/config.toml`:
  1161. ```bash
  1162. export GJC_WORKFLOW_GATE_WS='wss://localhost:9443/gjc-events'
  1163. clawhip subscribe validate
  1164. clawhip start
  1165. ```
  1166. ```toml
  1167. [[subscriptions]]
  1168. name = "gjc-workflow-gate"
  1169. enabled = true
  1170. kind = "websocket"
  1171. endpoint_env = "GJC_WORKFLOW_GATE_WS"
  1172. [subscriptions.filter]
  1173. discriminator_pointer = "/type"
  1174. discriminator_equals = "workflow_gate"
  1175. [[subscriptions.filter.predicates]]
  1176. pointer = "/gate/state"
  1177. equals = "ready"
  1178. [subscriptions.projection]
  1179. workflow_id = "/workflow/id"
  1180. gate_state = "/gate/state"
  1181. [subscriptions.adapter]
  1182. program = "/absolute/path/to/gjc-workflow-gate-adapter"
  1183. args = []
  1184. [subscriptions.routing]
  1185. tool = "gjc"
  1186. project = "my-project"
  1187. [[routes]]
  1188. event = "workflow.gate"
  1189. sink = "discord"
  1190. channel = "WORKFLOW_GATE_CHANNEL_ID"
  1191. format = "alert"
  1192. ```
  1193. A separate `question` subscription remains explicit and route-owned; it must not share a workflow-gate filter or silently inherit its channel:
  1194. ```toml
  1195. [[subscriptions]]
  1196. name = "gjc-question"
  1197. enabled = true
  1198. kind = "websocket"
  1199. endpoint_env = "GJC_QUESTION_WS"
  1200. [subscriptions.filter]
  1201. discriminator_pointer = "/type"
  1202. discriminator_equals = "question"
  1203. [subscriptions.projection]
  1204. question_id = "/question/id"
  1205. summary = "/question/summary"
  1206. [subscriptions.adapter]
  1207. program = "<path-to-clawhip>"
  1208. args = ["subscribe", "adapter", "question"]
  1209. [[routes]]
  1210. event = "workflow.question"
  1211. sink = "discord"
  1212. channel = "QUESTIONS_CHANNEL_ID"
  1213. format = "compact"
  1214. ```
  1215. 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.
  1216. 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 in

Free to use. If it’s helped, pass it on.