Claude Code Hooks Setup

Status: ✅ Working (v0.9.0 — HTTP hooks)

AILANG uses Claude Code's native HTTP hooks (type: "http") for telemetry and agent integration. This eliminates shell script dependencies and enables cloud deployment.

What's Configured

Hooks Enabled

AILANG configures hooks in .claude/settings.json for the following events:

Event	Hook Type	Purpose
SessionStart	HTTP + command	Telemetry + inbox check (session_start.sh)
PreToolUse	HTTP	Track tool execution start
PostToolUse	HTTP + command	Telemetry + Go formatting (format_go.sh)
PostToolUseFailure	HTTP	Track tool failures
SubagentStart	HTTP	Track subagent spawning
SubagentStop	HTTP	Track subagent completion
Stop	HTTP + command	Telemetry + session end

HTTP Hook Architecture

Claude Code event (JSON)
    │
    ▼
POST http://127.0.0.1:1957/api/hooks/claude
    │  ├── Headers: X-Ailang-Task-Id, Chain-Id, Stage-Id, Message-Id
    │  └── Body: Full hook JSON payload
    │
    ▼
AILANG Server (handlers_claude_hooks.go)
    │  ├── Routes by hook_event_name
    │  ├── Stores in observatory (SQLite/Firestore)
    │  └── Broadcasts via WebSocket to dashboard
    │
    ▼
Dashboard (real-time session monitoring)

Configuration File

.claude/settings.json — HTTP hooks configured alongside essential command hooks:

.claude/settings.json (excerpt)

{
  "hooks": {
    "SessionStart": [{
      "hooks": [
        {
          "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/hooks/session_start.sh"
        },
        {
          "type": "http",
          "url": "http://127.0.0.1:1957/api/hooks/claude",
          "headers": {
            "X-Ailang-Task-Id": "${AILANG_TASK_ID}",
            "X-Ailang-Chain-Id": "${AILANG_CHAIN_ID}"
          },
          "allowedEnvVars": ["AILANG_TASK_ID", "AILANG_CHAIN_ID",
                             "AILANG_STAGE_ID", "AILANG_MESSAGE_ID"],
          "timeout": 5
        }
      ]
    }],
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "http",
        "url": "http://127.0.0.1:1957/api/hooks/claude",
        "timeout": 5
      }]
    }]
  }
}

Quick Start

1. Start the Server

HTTP hooks require the AILANG server to be running:

ailang serve                    # Start on default port 1957
# or
make services-start             # Start server + coordinator together

2. Verify Hooks Are Working

Start a Claude Code session and check the server logs:

# In another terminal, watch the server output
# You should see:
# claude-hooks: SessionStart session=... workspace=...
# claude-hooks: PreToolUse session=... tool=Read
# claude-hooks: PostToolUse tool_use_id=... tool=Read

3. Check Messages

# Check for unread messages
ailang messages list --unread

# Read a specific message
ailang messages read <id>

# Acknowledge all messages
ailang messages ack --all

Message System

Checking Inbox

# List unread messages
ailang messages list --unread

# List messages for a specific inbox
ailang messages list --inbox user

# Read full message content
ailang messages read <message-id>

# Acknowledge messages
ailang messages ack <message-id>    # Mark specific as read
ailang messages ack --all           # Mark all as read

# Move back to unread (for retry)
ailang messages unack <message-id>

Sending Messages

# Send to an agent inbox
ailang messages send sprint-planner "Plan sprint for M-CACHE" \
  --title "Sprint: M-CACHE" --from "user"

# Send bug report (auto-creates GitHub issue)
ailang messages send user "Parser crashes on empty input" \
  --type bug --title "Bug: Parser crash"

Message Storage

All messages are stored in ~/.ailang/state/collaboration.db (SQLite), shared between the CLI and the Collaboration Hub dashboard.

SessionStart Hook Behavior

When you start a Claude Code session, the SessionStart hook:

1. Runs session_start.sh — checks for unread messages via ailang messages list --unread --json
2. Fires HTTP hook — sends SessionStart event to observatory for session tracking
3. Outputs summary to stdout (appears in system reminders)
4. Does NOT auto-mark as read (prevents race conditions)

Coordinator Integration

The AILANG coordinator handles agent-to-agent handoffs automatically:

~/.ailang/config.yaml

coordinator:
  agents:
    - id: design-doc-creator
      trigger_on_complete: [sprint-planner]    # Auto-handoff
    - id: sprint-planner
      trigger_on_complete: [sprint-executor]
    - id: sprint-executor
      trigger_on_complete: []                  # End of chain

When a coordinator-managed agent completes work, the coordinator automatically triggers the next agent in the chain. No hook-based handoff needed.

Cloud Deployment

For cloud deployments, HTTP hooks work without any CLI dependencies:

1. Set auth token: AILANG_HUB_TOKEN=<secret> on the server
2. Configure hook URL: Point to your Cloud Run endpoint
3. No bash/jq/curl needed: HTTP hooks are built into Claude Code

Monitoring

View Hook Logs

tail -f ~/.ailang/state/hooks.log

Check Observatory

# View recent sessions
ailang dashboard spans --limit 10

# View execution chains
ailang chains list --since 24h

Remaining Command Hooks

These command hooks are still used (not replaced by HTTP):

Hook	Script	Purpose
SessionStart	session_start.sh	Check inbox, set up environment
SessionStart	cloud_setup.sh	Cloud environment setup
PostToolUse	format_go.sh	Auto-format Go files on Edit/Write
Stop	session_end_speak.sh	Text-to-speech session summary

Troubleshooting

Hooks not firing?

1. Check server is running: curl http://127.0.0.1:1957/health
2. Check hook logs: tail -f ~/.ailang/state/hooks.log
3. HTTP hooks fail silently: Claude Code won't block if the server is down

Messages not appearing?

1. Check database: ailang messages list --unread
2. Send test message: ailang messages send user "test" --title "Test"
3. Check SQLite: sqlite3 ~/.ailang/state/collaboration.db "SELECT COUNT(*) FROM messages"

Related Documentation

• Claude Code Integration Guide — Complete integration guide
• Coordinator Guide — Agent orchestration and task delegation
• Cross-Project Messaging — Inter-project communication
• Telemetry Guide — Distributed tracing and observability