HAP — Human-Agent Protocol

A universal protocol for symbiotic collaboration between humans and autonomous AI agents.

HAP enables AI agents to request human decisions in a structured, auditable, and latency-safe manner. Agents never block — they create tickets with defined timeout behaviors, allowing graceful degradation or escalation.

Shared SQLite database (~/.hap/hap.db) connects all components. The MCP server exposes HAP operations as tools that any AI agent can call. Humans approve/reject via CLI or desktop app.

Quick Start

1. Install

git clone https://github.com/spinualexandru/humanagentprotocol.git
cd hap
npm install

2. Run Tests

npm test

3. Configure Your AI Tool

Claude Code

Already configured via .mcp.json in the project root. Or add globally:

claude mcp add --transport stdio hap-bridge -- npx tsx packages/mcp-server/src/index.ts

Replace Claude's built-in approval system with HAP:

Add a PreToolUse hook to your project's .claude/settings.local.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsx /path/to/hap/packages/cli/src/hook.ts",
            "timeout": 310000
          }
        ]
      }
    ]
  }
}

Now every tool call (Bash, Edit, Write, etc.) creates a HAP ticket instead of showing Claude's standard permission prompt. Read-only tools (Read, Glob, Grep) are auto-approved. Write/execute tools block until you approve:

[HAP] Ticket tk_a1b2c3 created — Run command: npm test
[HAP] Approve: hap approve tk_a1b2c3 | Reject: hap reject tk_a1b2c3

Approve from another terminal or the Tauri app — Claude continues immediately.

Risk is scored per tool type:

Codex CLI

# Add to your Codex MCP configuration
codex mcp add hap-bridge --stdio -- npx tsx /path/to/hap/packages/mcp-server/src/index.ts

OpenCode

Add to your OpenCode MCP config:

{
  "mcpServers": {
    "hap-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/path/to/hap/packages/mcp-server/src/index.ts"],
      "env": { "HAP_HUMAN_ID": "human:yourname" }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json or user settings:

{
  "servers": {
    "hap-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/path/to/hap/packages/mcp-server/src/index.ts"],
      "env": { "HAP_HUMAN_ID": "human:yourname" }
    }
  }
}

Copilot CLI

Uses the same MCP configuration as VS Code Copilot.

4. Use the CLI

# List pending tickets
npx tsx packages/cli/src/index.ts inbox

# Show ticket details
npx tsx packages/cli/src/index.ts show tk_abc123

# Approve a ticket
npx tsx packages/cli/src/index.ts approve tk_abc123 "LGTM"

# Reject a ticket
npx tsx packages/cli/src/index.ts reject tk_abc123 "Needs tests"

# Acknowledge (pause timer)
npx tsx packages/cli/src/index.ts ack tk_abc123 "Reviewing..."

# Verify event log integrity
npx tsx packages/cli/src/index.ts verify

5. Build the Tauri Desktop App

cd packages/tauri-app
npm install
cargo tauri dev     # Development mode
cargo tauri build   # Production build

MCP Tools

The MCP server exposes these tools to AI agents:

Ticket Lifecycle

PENDING → DELIVERED → ACKED → APPROVED / REJECTED / CHANGES_REQUESTED
    ↓          ↓         ↓
    └──────────┴─────────┴──→ CANCELED (from any non-terminal state)
                              EXPIRED  (from PENDING or DELIVERED on timeout)

• Lease timer starts at DELIVERED, pauses at ACKED
• On timeout: auto_approve, auto_reject, or cancel
• Risk scoring: 0.0-1.0 based on change scope, environment, and confidence
• High-risk (≥0.7): Requires step-up confirmation (typed_confirmation="approve production")

Environment Variables

Packages

Event Log

All operations produce an append-only event log with SHA-256 hash chaining for integrity verification:

npx tsx packages/cli/src/index.ts events   # View event log
npx tsx packages/cli/src/index.ts verify   # Verify integrity

License

Protocol Specification: CC BY 4.0 Reference Runtime: Apache 2.0