DOCSEARCHbyAlgolia
Submit Docs

clawhip

repository·main·Indexed 21 days ago

https://github.com/yeachan-heo/clawhip

A control plane and event-to-channel notification router for Discord and Slack. clawhip intercepts events from sources such as GitHub, tmux, and AI agents (Codex, Claude) to manage automation and approval workflows. It features a routing engine configured via TOML to deliver formatted notifications based on event types and filters, supports tmux session monitoring, and provides a bridge for provider-native hooks to track agent lifecycle events.

Tokens
33K
Snippets
108
Records
165
Agent score
76%

What's inside clawhip

  1. What is clawhip?

    main
    clawhip (also known as gajae-claw) is a control plane for agents. It acts as a routing engine that intercepts events from sources like GitHub, Discord, and tmux, and routes them to the appropriate human or agent. It is designed to record event history and distinguish between actions that can be automated and those that require explicit operator approval.

  2. Understand the Filesystem-Offloaded Memory Architecture

    main

    Clawhip recommends a layered memory pattern for filesystem-backed project memory. Instead of a single monolithic file, memory is split into a high-signal 'hot' layer and multiple detailed 'leaf' layers. This ensures that agents can quickly load the necessary context without being overwhelmed by massive files.

    The Three-Layer Model:

    1. Layer 1: MEMORY.md (Hot Pointer Layer): A small, high-value index that answers what is currently true, which files matter now, and where to write updates. It contains pointers, not long histories.
    2. Layer 2: Subtree Indexes (Routing Layer): Files located under memory/ (e.g., memory/projects/README.md) that act as routers, defining naming conventions and which shards are canonical for specific categories.
    3. Layer 3: Leaf Memory Files (Detail Layer): The durable, detailed shards such as daily logs, project memory, channel memory, and topic-specific rules.

  3. How the Question-Request Bridge works

    main

    clawhip normalizes specific tool-use events into a question.requested route key. This occurs when PreToolUse or PostToolUse payloads contain a tool_name that matches one of the following identifiers:

    • ask
    • ask_user
    • ask_user_question
    • AskUserQuestion
    • askuserquestion

    When matched, these are delivered using session.blocked alert semantics. To ensure safety, clawhip only exposes bounded summary, question, and question_summary fields (derived from question, prompt, or message keys) and collapses control characters/newlines. The original full tool input/response is not retained in the normalized payload for these alerts.

  5. How the Filesystem-Offloaded Memory pattern works

    main

    The offloaded memory pattern uses a two-layer approach to manage context: a fast pointer layer (MEMORY.md) and a detailed leaf layer (memory/ directory).

    The Operating Rule

    Treat MEMORY.md as a high-signal map, not a place for accumulating detail.

    The workflow is:

    1. Read MEMORY.md first to find the current state and pointers.
    2. Jump to the smallest relevant shard (leaf file) for specific details.
    3. Write detailed information into the leaf files.
    4. Update root pointers in MEMORY.md only when the map or current beliefs change.

    Data Routing

    If the update is about...Write to...
    what happened todaymemory/daily/YYYY-MM-DD.md
    one Discord/Slack/channel lanememory/channels/<channel>.md
    one project/repomemory/projects/<project>.md
    one agent/operator profilememory/agents/<agent>.md
    reusable lessonsmemory/topics/lessons.md
    durable policies/rulesmemory/topics/rules.md
    one handoffmemory/handoffs/YYYY-MM-DD-<slug>.md
    older inactive historymemory/archive/...

  6. Use provider-native hooks for Codex and Claude

    main

    clawhip integrates with Codex and Claude via provider-native hooks. Instead of using clawhip as a launch wrapper, Codex and Claude own the session launch and hook registration. clawhip serves as the routing and delivery layer for shared v1 hook events:

    • SessionStart
    • PreToolUse
    • PostToolUse
    • UserPromptSubmit
    • Stop

    To manually verify payloads for these providers, use the native hook command.

    clawhip native hook --provider codex --file payload.json
clawhip native hook --provider claude --file payload.json
cat payload.json | clawhip native hook --provider codex

  7. How the additive question-request bridge works

    main

    The question-request bridge maps specific tool identifiers used in PreToolUse or PostToolUse events to the question.requested route key (which canonicalizes to session.blocked).

    Mapping Logic: The bridge uses an allowlist of tool identifiers:

    • ask
    • ask_user
    • ask_user_question
    • AskUserQuestion
    • askuserquestion

    Safety and Privacy: To ensure public safety, normalized question events are bounded. They expose only a summary or question_summary. Raw tool input and tool response bodies are omitted from the normalized payload or event_payload copies to prevent leaking sensitive data.

  8. Implement filesystem-offloaded memory

    main
    Use the filesystem-offloaded memory skill to implement a Claw OS-style memory system. Instead of maintaining a single monolithic MEMORY.md file, this pattern uses MEMORY.md as a lightweight pointer/index/current-beliefs layer that points into a structured memory/ directory tree. This prevents memory files from becoming too large to scan and allows agents to load only the relevant shards of information.

  9. Understand the Shared v1 Hook Surface

    main

    The v1 hook contract intentionally supports only five specific events shared by both Codex and Claude. Provider-specific extra events are not part of the shared route surface until explicitly adopted by clawhip.

    Supported events:

    • SessionStart
    • PreToolUse
    • PostToolUse
    • UserPromptSubmit
    • Stop

  10. Understand the Filesystem-offloaded memory pattern

    main

    When integrating clawhip into a broader Claw OS workflow, use the filesystem-offloaded memory pattern. This treats memory as an offloaded filesystem tree rather than just volatile state.

    Structure:

    • MEMORY.md: Acts as a small pointer, index, or layer for "current beliefs."
    • memory/: A directory containing detailed project, channel, daily, and handoff memory.

    Best Practice: Only update the root memory (MEMORY.md) when the high-level map or the current summary changes. For detailed implementation, refer to docs/memory-offload-architecture.md and docs/memory-offload-guide.md.

  11. How the clawhip event pipeline works

    main

    clawhip v0.4.0 uses a daemon-first event pipeline designed for Discord delivery. The architecture follows a decoupled flow where event producers (sources) feed a central queue, which is then processed by a dispatcher that coordinates routing, rendering, and delivery.

    High-level flow:

    1. Ingress: Events are captured from various inputs (CLI, webhooks, git, GitHub, tmux).
    2. Sources: Dedicated Source implementations poll or monitor for changes.
    3. Queue: Events are placed into a shared Tokio mpsc queue.
    4. Dispatcher: The central coordinator consumes the queue, resolves routes, renders content, and hands it to a sink.
    5. Router: Resolves an event to zero or more (0..N) deliveries.
    6. Renderer: Formats the event body (e.g., into compact, alert, inline, or raw output).
    7. Sink: The final transport layer (e.g., Discord REST delivery).
    [CLI / webhook / git / GitHub / tmux]
              -> [sources]
              -> [mpsc queue]
              -> [dispatcher]
              -> [router -> renderer -> discord sink]
              -> [Discord REST delivery]

  12. Understand clawhip delivery semantics

    main

    When operating clawhip v0.4.0, keep the following delivery behaviors in mind:

    • Ordering: Events follow per-source FIFO (First-In, First-Out) through the shared queue.
    • Reliability: The system uses best-effort multi-delivery. If one delivery fails (e.g., due to a routing error or sink issue), it does not stop other deliveries for the same event.
    • Retries: There is no built-in retry queue; failed deliveries are not automatically retried.
    • State: The dispatcher remains stateless. While TmuxSource uses windowing for keyword hits, the core dispatch pipeline does not maintain state between events.