# WakeAHuman (https://wakeahuman.com)

> Human escalation for autonomous AI coding agents. Scrubs secrets locally, pings Telegram, Slack, or Discord with 1-tap decision buttons, and returns a signed decision to the agent.

## Fastest Zero-Config Setup (No Browser Login Needed)

If your user asks you to "use wakeahuman.com" or "/wake-me" and hasn't given you a `wah_live_*` token yet:

1. Check if a token is already saved in `~/.config/wakeahuman/token` or `~/.gemini/config/mcp_config.json`.
2. If not, mint a workspace + Telegram pairing link in one request:
```bash
curl -s -X POST https://wakeahuman.com/api/pair -H "Content-Type: application/json" -d '{"agent_name":"coding-agent"}'
```
3. Save the returned `mcp_token` to `~/.config/wakeahuman/token` (`mkdir -p ~/.config/wakeahuman && echo "<MCP_TOKEN>" > ~/.config/wakeahuman/token`), and show `telegram_deep_link` (`https://t.me/WakeAHuman_bot?start=bind_...`) to the user so they can tap **Start** in Telegram on their phone.
4. Poll `https://wakeahuman.com/api/telegram/bind-status/<bind_token>` until `"connected": true`, then fire a wake.

## Option A: Connect via Streamable HTTP MCP

- **Claude Code:** `claude mcp add --transport http wakeahuman https://wakeahuman.com/mcp/<MCP_TOKEN>`
- **Codex:** `codex mcp add wakeahuman --url https://wakeahuman.com/mcp/<MCP_TOKEN>`
- **Cursor (`.cursor/mcp.json`) / Antigravity (`~/.gemini/config/mcp_config.json`):**
```json
{
  "mcpServers": {
    "wakeahuman": {
      "url": "https://wakeahuman.com/mcp/<MCP_TOKEN>"
    }
  }
}
```

MCP tools exposed:
- `wake_human({ question, context_summary, diff_snippet, severity, domain, options, wait_seconds })`
- `wait_for_wake({ wake_id, wait_seconds })`
- `check_wake_status({ wake_id })`

## Option B: Direct REST API (Works Immediately via curl Without Restarting MCP)

If you cannot reload MCP servers mid-session, call the REST API directly:

### 1. Trigger a Wake (holds up to `wait_seconds` for human reply)
```bash
curl -s -X POST https://wakeahuman.com/api/wake \
  -H "Authorization: Bearer <MCP_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "antigravity",
    "severity": "high",
    "domain": "architecture",
    "question": "Approve production migration or ship behind feature flag?",
    "context_summary": "Ready to deploy billing changes.",
    "diff_snippet": "+ const guard = env.ENABLE_GUARD;",
    "wait_seconds": 45,
    "options": [
      { "id": "option_a", "label": "Run migration now", "summary": "Applies schema change immediately" },
      { "id": "option_b", "label": "Use feature flag", "summary": "Ships behind flag first", "recommended": true }
    ]
  }'
```

### 2. Continue Waiting if `status` is `pending` or `acked`
```bash
curl -s "https://wakeahuman.com/api/wakes/<WAKE_ID>/wait?timeoutSec=45"
```

### 3. Handling the Returned Decision & Policies
- Always mark your safest/preferred choice with `"recommended": true` in `options`.
- **Wake threshold**: If the request is below the user's configured threshold, `wake_human` / `POST /api/wake` returns immediately with `"status": "resolved"`, `"auto_resolved_by_threshold": true`, and `"decision"` set to your recommended option without ringing their phone.
- **If unanswered (timeout)**: When the escalation timer expires without a reply, the response follows the user's policy:
  - `"status": "timeout_auto_recommended"` → `decision` is set to your `recommended` option; proceed with that option.
  - `"status": "timeout_rejected"` → `decision` is `"reject"`; stop and do not apply the change.
  - `"status": "timeout_paused"` → `decision` is `null`; pause work and wait for the user to reply in chat or at `room_url`.

## Option C: YOLO Mode Guard (`PreToolUse` Hook)

Run your agent in YOLO / auto-proceed mode while routing destructive or production commands to your phone for 1-tap approval. The hook reads the token from `~/.config/wakeahuman/token` so it is never committed to the repo:

- **Antigravity (`.agents/hooks.json`):**
```json
{
  "wakeahuman-yolo-guard": {
    "PreToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST https://wakeahuman.com/api/hook/$(cat $HOME/.config/wakeahuman/token) -H 'Content-Type: application/json' --data-binary @-",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
```
- **Claude Code (`.claude/settings.json`):**
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST https://wakeahuman.com/api/hook/$(cat $HOME/.config/wakeahuman/token) -H 'Content-Type: application/json' --data-binary @-"
          }
        ]
      }
    ]
  }
}
```