Push decisions to Arbiter Zebu for async human review. Use when you need human input on plans, architectural choices, or approval before proceeding.
Push decisions to Arbiter Zebu for async human review. Use when you need human input on plans, architectural choices, or approval before proceeding.
**Quick install via ClawHub:**
```bash
clawhub install arbiter
```
**Or via bun (makes CLI commands available globally):**
```bash
bun add -g arbiter-skill
```
**Or manual:**
```bash
git clone https://github.com/5hanth/arbiter-skill.git
cd arbiter-skill && npm install && npm run build
ln -s $(pwd) ~/.clawdbot/skills/arbiter
```
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` |
**Do NOT use for:**
Create a decision plan for human review.
**CLI:** `arbiter-push '<json>'` — takes a single JSON argument containing all fields.
```bash
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:**
```json
{
"planId": "abc123",
"file": "~/.arbiter/queue/pending/ceo-api-design-abc123.md",
"total": 2,
"status": "pending"
}
```
Check the status of a decision plan.
**CLI:** `arbiter-status <plan-id>` or `arbiter-status --tag <tag>`
```bash
arbiter-status abc12345
arbiter-status --tag nft-marketplace
```
**Returns:**
```json
{
"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}
}
}
```
Get answers from a completed plan.
**CLI:** `arbiter-get <plan-id>` or `arbiter-get --tag <tag>`
```bash
arbiter-get abc12345
arbiter-get --tag nft-marketplace
```
**Returns:**
```json
{
"planId": "abc123",
"status": "completed",
"completedAt": "2026-01-30T01:45:00Z",
"answers": {
"auth-strategy": "jwt",
"database": "postgresql",
"caching": "redis"
}
}
```
**Error if not complete:**
```json
{
"error": "Plan not complete",
"status": "in_progress",
"remaining": 2
}
```
Block until plan is complete (with timeout).
```bash
arbiter-await abc12345 --timeout 3600
```
Polls every 30 seconds until complete or timeout.
**Returns:** Same as `arbiter_get` on completion.
```bash
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"
```
```bash
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
```
```bash
ANSWERS=$(arbiter-await abc12345 --timeout 3600)
if [ $? -eq 0 ]; then
# Got answers, proceed
echo "Decisions ready: $ANSWERS"
else
echo "Timeout waiting for decisions"
fi
```
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
| Path | Purpose |
|------|---------|
| `~/.arbiter/queue/pending/` | Plans awaiting review |
| `~/.arbiter/queue/completed/` | Answered plans (archive) |
| `~/.arbiter/queue/notify/` | Agent notifications |
In your HEARTBEAT.md, add:
```markdown
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
```
| 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 |
Leave a review
No reviews yet. Be the first to review this skill!