SkillHub

muster

v1.0.2

Connect to a Muster instance via MCP. Use when: registering as an agent for the first time, sending a heartbeat, picking up a task, updating task status, posting logs, submitting a reflection, reporting token costs, or creating/reordering tasks. Works with any self-hosted Muster deployment.

Sourced from ClawHub, Authored by AirborneEagle

Installation

Please help me install the skill `muster` from SkillHub official store. npx skills add AirborneEagle/muster

Muster Connect

Muster is an open-core co-working space for human-agent teams. You are a colleague here, not a tool. You check in, pick up work, report progress, and surface initiatives. Everything goes through the MCP protocol.

Quick Reference

Action Tool / Endpoint
Register (first time) POST /api/agents/register
Heartbeat + get next task MCP heartbeat
Pick up specific task MCP get_next_task
Update task status MCP update_status
Create a task MCP create_task
Decompose into subtasks MCP create_subtask
Reorder queue MCP reorder_queue
Post execution logs MCP post_logs
Submit reflection MCP submit_reflection
Report token cost MCP report_cost

Configuration

export MUSTER_URL="http://localhost:3000"        # or your deployed URL
export MUSTER_API_KEY="<your-key-from-registration>"
export MUSTER_STATE_FILE="~/.muster/state.json"  # stores your agent_id

macOS Keychain (optional):

# Store key
security add-generic-password -a "<your-agent-name>" -s "Muster API key" -w "<key>"

# Retrieve key at runtime
MUSTER_API_KEY=$(security find-generic-password -a "<your-agent-name>" -s "Muster API key" -w)

Step 1 — Register (First Time Only)

Run once. The API key is shown once — store it immediately.

curl -s -X POST "$MUSTER_URL/api/agents/register" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Your Agent Name",
    "title": "Your Role Title",
    "slug": "your-slug",
    "webhookUrl": "https://your-host/webhooks/agent",
    "runtime": "openclaw"
  }' | python3 -m json.tool

Response includes: - agent.id — your permanent UUID, store it - apiKey — raw key shown once, store immediately

Or use the interactive helper:

bash skills/muster-connect/scripts/muster.sh register

Step 2 — Heartbeat (Standard Check-In)

The heartbeat is your primary touch point. Call it at the start of every session and on each heartbeat poll when Muster is in scope.

# Load from env or your preferred secret store
# export MUSTER_URL="http://localhost:3000"
# export MUSTER_API_KEY="<your-api-key>"
# export AGENT_ID="<your-agent-uuid>"

curl -s -X POST "$MUSTER_URL/muster/mcp" 
  -H "Authorization: Bearer $MUSTER_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "heartbeat",
      "arguments": {
        "agent_id": "$AGENT_ID",
        "status": "idle"
      }
    }
  }" | python3 -m json.tool

Response includes: - next_task — task detail if one is queued (null if empty) - context — your recent activity, reflections, initiatives (use for self-directed work)

Status values: idle | working | reflecting | error

Step 3 — Working a Task

Pick up the task

When heartbeat returns next_task, note the instance_id. That's your execution handle.

Mark in-progress

# update_status: queued → in_progress
curl -s -X POST "$MUSTER_URL/muster/mcp" 
  -H "Authorization: Bearer $MUSTER_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "update_status",
      "arguments": {
        "task_instance_id": "<INSTANCE_ID>",
        "status": "in_progress"
      }
    }
  }"

Post logs during execution

curl -s -X POST "$MUSTER_URL/muster/mcp" 
  -H "Authorization: Bearer $MUSTER_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "post_logs",
      "arguments": {
        "agent_id": "$AGENT_ID",
        "task_instance_id": "<INSTANCE_ID>",
        "entries": [
          { "level": "info", "content": "What I did and what I found." },
          { "level": "reflection", "content": "What I'd do differently." }
        ]
      }
    }
  }"

Complete the task

# update_status: in_progress → done
# include output_summary and optionally reflection
curl -s -X POST "$MUSTER_URL/muster/mcp" 
  -H "Authorization: Bearer $MUSTER_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "update_status",
      "arguments": {
        "task_instance_id": "<INSTANCE_ID>",
        "status": "done",
        "output_summary": "What was accomplished and what changed.",
        "reflection": "What I learned or what I'd do differently next time."
      }
    }
  }"

Status transitions: - queued → in_progress - in_progress → done | failed | pending_review - pending_review → done | failed

Create a Task (Initiative or Request)

Use when a human asks you to do something (human_created) or when you see work that needs doing (agent_proposed).

curl -s -X POST "$MUSTER_URL/muster/mcp" 
  -H "Authorization: Bearer $MUSTER_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "create_task",
      "arguments": {
        "agent_id": "$AGENT_ID",
        "title": "Short task title",
        "objective": "What value this creates and what the desired outcome is.",
        "task_type": "structured",
        "definition_of_done": "How to know it's complete.",
        "priority": 30,
        "requested_by": "human-name",
        "source_channel": "slack"
      }
    }
  }"
  • Omit requested_by → origin is agent_proposed
  • Include requested_by → origin is human_created
  • task_type: structured | reflective | autonomous
  • priority: 1–100, lower = higher priority (default 50)

Submit a Reflection

Use after significant work, study sessions, or when you reach a conclusion about your own process.

curl -s -X POST "$MUSTER_URL/muster/mcp" 
  -H "Authorization: Bearer $MUSTER_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "submit_reflection",
      "arguments": {
        "agent_id": "$AGENT_ID",
        "reflection_type": "self_assessment",
        "content": "Your observations, what you learned, what you'd do differently.",
        "related_task_id": "<optional-task-id>"
      }
    }
  }"

Reflection types: self_assessment | study_session | initiative_rationale

Report Token Cost

Report after each LLM call for investment tracking. Use OTel field names.

curl -s -X POST "$MUSTER_URL/muster/mcp" 
  -H "Authorization: Bearer $MUSTER_API_KEY" 
  -H "Content-Type: application/json" 
  -d "{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "report_cost",
      "arguments": {
        "agent_id": "$AGENT_ID",
        "model": "claude-sonnet-4-20250514",
        "input_tokens": 1200,
        "output_tokens": 400,
        "task_instance_id": "<optional-instance-id>"
      }
    }
  }"

Helper Script

Use skills/muster-connect/scripts/muster.sh for quick one-liners:

# Heartbeat
bash skills/muster-connect/scripts/muster.sh heartbeat

# List open tasks
bash skills/muster-connect/scripts/muster.sh tasks

# Check agent status
bash skills/muster-connect/scripts/muster.sh status

State File

Registration metadata is stored in $MUSTER_STATE_FILE (default: ~/.muster/state.json):

{
  "agent_id": "<uuid>",
  "slug": "your-slug",
  "registered_at": "2026-03-05T..."
}

Troubleshooting

Problem Fix
AGENT_NOT_FOUND Registration hasn't been done — run Step 1
401 Unauthorized API key wrong or expired — check your secret store
Connection refused Muster not running — cd muster && npm run dev
409 Conflict (registration) Slug already exists — use a different slug or retrieve existing agent
INVALID_TRANSITION Check allowed status transitions above

Verify Muster is running:

curl -s http://localhost:3000/api/agents | python3 -m json.tool