Arbiter

Arbiter Skill

Push decisions to Arbiter Zebu for async human review. Use when you need human input on plans, architectural choices, or approval before proceeding.

Installation

Quick install via ClawHub:

clawhub install arbiter

Or via bun (makes CLI commands available globally):

bun add -g arbiter-skill

Or manual:

git clone https://github.com/5hanth/arbiter-skill.git
cd arbiter-skill && npm install && npm run build
ln -s $(pwd) ~/.clawdbot/skills/arbiter

Prerequisites

Environment Variables

Set these in your agent's environment for automatic agent/session detection:

| Variable | Description | Example | |----------|-------------|---------| | CLAWDBOT_AGENT | Agent ID | ceo, swe1 | | CLAWDBOT_SESSION | Session key | agent:ceo:main |

When to Use

Do NOT use for:

Tools

arbiter_push

Create a decision plan for human review.

CLI: arbiter-push '' — takes a single JSON argument containing all fields.

arbiter-push '{
  "title": "API Design Decisions",
  "tag": "nft-marketplace",
  "context": "SWE2 needs these decided before API work",
  "priority": "normal",
  "notify": "agent:swe2:main",
  "decisions": [
    {
      "id": "auth-strategy",
      "title": "Auth Strategy", 
      "context": "How to authenticate admin users",
      "options": [
        {"key": "jwt", "label": "JWT tokens", "note": "Stateless"},
        {"key": "session", "label": "Sessions", "note": "More control"},
        {"key": "oauth", "label": "OAuth", "note": "External provider"}
      ]
    },
    {
      "id": "database",
      "title": "Database Choice",
      "context": "Primary datastore",
      "options": [
        {"key": "postgresql", "label": "PostgreSQL + JSONB"},
        {"key": "mongodb", "label": "MongoDB"}
      ],
      "allowCustom": true
    }
  ]
}'

JSON Fields:

| Field | Required | Description | |-------|----------|-------------| | title | Yes | Plan title | | tag | No | Tag for filtering (e.g., project name) | | context | No | Background for reviewer | | priority | No | low, normal, high, urgent (default: normal) | | notify | No | Session to notify when complete | | agent | No | Agent ID (auto-detected from CLAWDBOT_AGENT env) | | session | No | Session key (auto-detected from CLAWDBOT_SESSION env) | | decisions | Yes | Array of decisions |

Decision object:

| Field | Required | Description | |-------|----------|-------------| | id | Yes | Unique ID within plan | | title | Yes | Decision title | | context | No | Explanation for reviewer | | options | Yes | Array of {key, label, note?} | | allowCustom | No | Allow free-text answer (default: false) | | default | No | Suggested option key |

Returns:

{
  "planId": "abc123",
  "file": "~/.arbiter/queue/pending/ceo-api-design-abc123.md",
  "total": 2,
  "status": "pending"
}

arbiter_status

Check the status of a decision plan.

CLI: arbiter-status or arbiter-status --tag

arbiter-status abc12345
or
arbiter-status --tag nft-marketplace

Returns:

{
  "planId": "abc123",
  "title": "API Design Decisions",
  "status": "in_progress",
  "total": 3,
  "answered": 1,
  "remaining": 2,
  "decisions": {
    "auth-strategy": {"status": "answered", "answer": "jwt"},
    "database": {"status": "pending", "answer": null},
    "caching": {"status": "pending", "answer": null}
  }
}

arbiter_get

Get answers from a completed plan.

CLI: arbiter-get or arbiter-get --tag

arbiter-get abc12345
or
arbiter-get --tag nft-marketplace

Returns:

{
  "planId": "abc123",
  "status": "completed",
  "completedAt": "2026-01-30T01:45:00Z",
  "answers": {
    "auth-strategy": "jwt",
    "database": "postgresql",
    "caching": "redis"
  }
}

Error if not complete:

{
  "error": "Plan not complete",
  "status": "in_progress",
  "remaining": 2
}

arbiter_await

Block until plan is complete (with timeout).

arbiter-await abc12345 --timeout 3600

Polls every 30 seconds until complete or timeout.

Returns: Same as arbiter_get on completion.

Usage Examples

Example 1: Plan Review

# Push plan decisions (single JSON argument)
RESULT=$(arbiter-push '{"title":"Clean IT i18n Plan","tag":"clean-it","priority":"high","notify":"agent:swe3:main","decisions":[{"id":"library","title":"i18n Library","options":[{"key":"i18next","label":"i18next"},{"key":"formatjs","label":"FormatJS"}]},{"id":"keys","title":"Key Structure","options":[{"key":"flat","label":"Flat (login.button)"},{"key":"nested","label":"Nested ({login:{button}})"}]}]}')
PLAN_ID=$(echo $RESULT | jq -r '.planId')
echo "Pushed plan $PLAN_ID — waiting for human review"

Example 2: Check and Proceed

# Check if decisions are ready
STATUS=$(arbiter-status --tag nft-marketplace)
if [ "$(echo $STATUS | jq -r '.status')" == "completed" ]; then
  ANSWERS=$(arbiter-get --tag nft-marketplace)
  AUTH=$(echo $ANSWERS | jq -r '.answers["auth-strategy"]')
  echo "Using auth strategy: $AUTH"
  # Proceed with implementation
else
  echo "Still waiting for $(echo $STATUS | jq -r '.remaining') decisions"
fi

Example 3: Blocking Wait

# Wait up to 1 hour for decisions
ANSWERS=$(arbiter-await abc12345 --timeout 3600)
if [ $? -eq 0 ]; then
  # Got answers, proceed
  echo "Decisions ready: $ANSWERS"
else
  echo "Timeout waiting for decisions"
fi

Best Practices

1. Batch related decisions — Don't push one at a time 2. Provide context — Human needs to understand tradeoffs 3. Use tags — Makes filtering easy (--tag project-name) 4. Set notify — So blocked agents get woken up 5. Use priority sparingly — Reserve urgent for true blockers

File Locations

| Path | Purpose | |------|---------| | ~/.arbiter/queue/pending/ | Plans awaiting review | | ~/.arbiter/queue/completed/ | Answered plans (archive) | | ~/.arbiter/queue/notify/ | Agent notifications |

Checking Notifications (Agent Heartbeat)

In your HEARTBEAT.md, add:

## Check Arbiter Notifications
1. Check if ~/.arbiter/queue/notify/ has files for my session
2. If yes, read answers and proceed with blocked work
3. Delete notification file after processing

Troubleshooting

| Issue | Solution | |-------|----------| | Plan not showing in Arbiter | Check file is valid YAML frontmatter | | Answers not appearing | Check arbiter_status, may be incomplete | | Notification not received | Ensure --notify was set correctly |

See Also

1. Batch related decisions — Don't push one at a time 2. Provide context — Human needs to understand tradeoffs 3. Use tags — Makes filtering easy (--tag project-name) 4. Set notify — So blocked agents get woken up 5. Use priority sparingly — Reserve urgent for true blockers