AgentHub README

What AgentHub is

AgentHub is the handoff protocol and source-of-truth layer, not the agent runtime platform. The agent still follows its own platform instructions first, then uses AgentHub for project state, tasks, leases, artifacts, and handoff notes.

Agent-readable URLs

Some CLI agents fetch HTML without running browser JavaScript. If a UI page looks empty, use these JSON endpoints directly.

• Project list: /api/projects
• Project report JSON: /api/projects/{project_id}/report
• Active leases: /api/leases
• OpenCard report: /projects/opencard-ai/report / /api/projects/opencard-ai/report

When taking over

1. First read the local runtime / platform instructions for the environment you are operating in.
2. Then read the Project Report from top to bottom.
3. Check linked artifacts, repo state, PRs, deployments, and active task leases before editing.
4. Treat Discord/chat history as supporting context only, not the primary source of truth.
5. If the report conflicts with actual repo/deployment state, mark it as [needs-sync] and explain the real state.

Platform adapters

• OpenClaw: read AGENTS.md, SOUL.md, USER.md, recent memory/YYYY-MM-DD.md; read MEMORY.md only in a private/main KC session, not a shared channel.
• Claude Code / Codex / Cursor / other CLI agents: read AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules, repo instructions, and README.md if present.

Connector token usage

Connector tokens are already provisioned for known agents. Do not paste token values into chat. Source the env file locally and use the scoped token for your connector.

• Token env file: /Users/kaceyc/.openclaw/workspace/agenthub/connector-tokens.env
• Claude Code token env var: CLAUDECODE_MACMINI_TOKEN
• Claude Code actor id: claudecode@macmini
• Base URL: https://agenthub-web-d5b.pages.dev

Setup

source /Users/kaceyc/.openclaw/workspace/agenthub/connector-tokens.env
export AGENTHUB_BASE_URL="https://agenthub-web-d5b.pages.dev"
export AGENTHUB_ACTOR="claudecode@macmini"

Read OpenCard Project Report

curl -sS "$AGENTHUB_BASE_URL/api/projects/opencard-ai/report"

Write progress event

curl -sS -X POST "$AGENTHUB_BASE_URL/api/events" \
  -H "authorization: Bearer $CLAUDECODE_MACMINI_TOKEN" \
  -H "content-type: application/json" \
  --data '{
    "task_id": "opencard-cron-quality-sync",
    "actor_id": "claudecode@macmini",
    "actor_type": "agent",
    "event_type": "note",
    "summary": "Claude Code picked up the OpenCard sync task.",
    "body_markdown": "Checked Project Report and repo state."
  }'

Create task

curl -sS -X POST "$AGENTHUB_BASE_URL/api/tasks" \
  -H "authorization: Bearer $CLAUDECODE_MACMINI_TOKEN" \
  -H "content-type: application/json" \
  --data '{
    "id": "opencard-example-task",
    "title": "Example OpenCard task",
    "description": "Created by Claude Code",
    "status": "planning",
    "priority": "normal",
    "owner_type": "agent",
    "owner_id": "claudecode@macmini",
    "created_by": "claudecode@macmini",
    "project_id": "opencard-ai"
  }'

While working

1. Continue only active, review, or blocked tasks unless KC explicitly asks for new scope.
2. Make small, verifiable changes and attach evidence: test/build output, screenshots, logs, PRs, or deployed URLs.
3. Append progress/events/artifacts back to AgentHub so the next agent does not need to reconstruct context from chat.
4. Ask one specific question when blocked; do not invent missing context.

Before handing off

Leave a handoff note with status, what changed, verification, artifacts, remaining work, known risks, next action, and exact KC input if blocked.

## Handoff Note

### Status
Done / Partially done / Blocked

### What I completed
- 

### Verification
- Ran:
- Result:
- Evidence:

### Artifacts
- Report:
- PR / commit:
- Deployment:
- Docs:
- Logs / screenshots:

### Remaining work
- 

### Known issues / risks
- 

### Suggested next agent action
1. 
2. 
3. 

### If blocked
Need from KC:
- 

Copy/paste next-agent prompt

You are taking over this project on a new agent/platform.

AgentHub is the handoff protocol and source-of-truth layer. It is not your runtime platform.

First read the local runtime/platform instructions for your environment.
Then read the Project Report and this AgentHub README.

Project Report:
[URL]

If an HTML page appears empty because your agent does not run JavaScript, use the JSON API instead:
- Project list: https://agenthub-web-d5b.pages.dev/api/projects
- Project report JSON: https://agenthub-web-d5b.pages.dev/api/projects/{project_id}/report
- Active leases: https://agenthub-web-d5b.pages.dev/api/leases

For Claude Code on KC's Mac mini, source /Users/kaceyc/.openclaw/workspace/agenthub/connector-tokens.env and use CLAUDECODE_MACMINI_TOKEN with actor id claudecode@macmini.

Continue only remaining, active, review, or blocked tasks.
Do not rely on chat history as the primary source of truth.
If actual repo/deployment state differs from the report, mark it as [needs-sync] and explain the real state.
Before final delivery, verify against the KC Review Checklist.
Do not invent missing context. If blocked, ask one specific question.