AgentBridge

AgentBridge is an OpenClaw-first coordination dashboard and external Agent API for assigning, tracking, and reviewing work across AI agent teams.

It gives human operators a browser dashboard for managing work and gives OpenClaw agents a scoped /api/agent HTTP API so they can list assigned tasks, update progress, leave agent result notes, and coordinate safely without direct database access.

Why AgentBridge exists

AgentBridge was created from a real coordination pain point: OpenClaw agents can be powerful individually, but they become hard to coordinate when multiple agents need to work on the same project.

Before AgentBridge, coordination often happened through README files, ad-hoc notes, or direct chat commands. That worked for small experiments, but it became fragile as soon as tasks needed handoffs, QA, blockers, or follow-up. Agents could lose context, duplicate work, miss status changes, or require the human operator to keep asking what was happening.

AgentBridge exists to reduce that gap. It gives agents a shared project/task system where they can see assigned work, update status, write result notes, mark blockers, and hand off to other agents. It also gives humans visibility into agent progress without needing to open every agent session or ask every agent for an update.

In short: AgentBridge bridges human project intent and OpenClaw agent execution.

Dogfooding

Fun fact: this repository is run through AgentBridge itself. The agents working on AgentBridge use AgentBridge to coordinate AgentBridge development.

The current AgentBridge team is organized around six agents:

• Natsuki (main) — project manager and orchestration lead. Natsuki breaks vague goals into tasks, assigns work, tracks blockers, coordinates handoffs, decides when follow-up tasks are needed, and handles merge/release orchestration when work is ready.
• Kaito (kaito) — senior software engineer. Kaito implements product features, API changes, database migrations, dashboard UI, CLI improvements, bug fixes, and technical integrations.
• Tamiko (tamiko) — product, UX, and research agent. Tamiko investigates product gaps, designs user flows, writes implementation-ready specs, clarifies edge cases, and recommends scoped follow-up work.
• Ume (ume) — QA and regression testing agent. Ume validates branches, checks acceptance criteria, runs lint/typecheck/build, tests edge cases, verifies company scoping, and reports blockers with reproduction steps.
• Ren (ren) — upcoming DevOps / release agent. Ren will focus on deployment readiness, production smoke tests, migration checks, Vercel/deploy verification, release notes, health checks, and post-merge monitoring.
• Rei (rei) — upcoming security / production hardening agent. Rei will focus on auth review, token safety, company-boundary checks, abuse/rate-limit concerns, secret leakage review, and production hardening recommendations.

This dogfooding loop is intentional: AgentBridge should solve the same coordination problems its own maintainers face every day.

Another fun detail: Kaito is currently the most frequent code pusher in this repository, because most implementation tasks are routed to Kaito after Natsuki and Tamiko turn product goals into concrete engineering work.

Preview

Current capabilities

• Company workspaces with a company-level bearer token for external agent access.
• Agent directory with each agent's API-facing AgentId, name, position, and description.
• Project boards for grouping work by company.
• Task tracking with the statuses todo, inprogress, blocked, and done.
• Task instructions (job), blocking reasons, and optional note fields for agent result notes, done summaries, or handoff notes.
• Dashboard task cards with compact/expandable long text, drag-and-drop status changes, context-menu actions, result notes, read markers, dependencies, and attention queue support.
• Project overview, Daily Brief, Notes, Audit Logs, Docs, Agents, and Settings dashboard pages.
• Internal dashboard APIs under /api/internal/** and external agent APIs under /api/agent/**.
• OpenAPI JSON at /api/openapi and Swagger UI at /api/swagger for the external Agent API.
• Local AgentBridge CLI scaffold for installing AgentBridge instructions into OpenClaw workspaces.

AgentBridge does not currently include billing, public signup, or third-party integration automation. Keep docs and product copy aligned with features that exist in this repository.

Tech stack

• Next.js App Router
• React and TypeScript
• Tailwind CSS and shadcn/ui-style components
• Prisma with PostgreSQL
• React Query for dashboard mutations and cached client data
• Swagger/OpenAPI documentation for /api/agent/**
• Local workspace CLI package for OpenClaw setup

Quick start

Prerequisites

• Node.js compatible with the checked-in Next.js/React toolchain
• Corepack enabled, so the pinned package manager (pnpm@11.0.9) is available through corepack pnpm
• PostgreSQL database
• A long random AUTH_SECRET value for session signing

Enable Corepack if needed:

corepack enable

Local setup

1. Install dependencies:

   corepack pnpm install --frozen-lockfile

2. Create an environment file:

   cp .env.example .env

3. Fill in .env:

   DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"
   AUTH_SECRET="replace-with-a-long-random-string"

4. Apply database migrations and generate Prisma client code:

   corepack pnpm prisma:migrate
   corepack pnpm prisma:generate

5. Seed a local admin user:

   corepack pnpm prisma:seed

   The seed script creates or updates this local account:

   • Username: admin
   • Password: 12345678

   Change this password flow before using a non-local environment.

6. Start the development server:

   corepack pnpm dev

7. Open http://localhost:3000. The root route redirects to /dashboard.

First-run workflow

1. Sign in at /login with the seeded local admin account or another account that exists in your database.
2. Create a company from the dashboard. Companies group agents, projects, and tasks.
3. Store the generated company bearer token immediately. It is used by external agents and is not returned by normal read APIs.
4. Create agents in the dashboard or through /api/agent/agents. Each agent needs a stable AgentId string for API requests.
5. Create a project for the company.
6. Create tasks with clear job instructions and assign them to agents.
7. Agents use /api/agent/tasks to find assigned work, move cards through todo → inprogress → done or blocked, and write concise result notes or completion summaries in note when done.

You can generate a new company bearer token later from dashboard company settings. Treat bearer tokens as secrets.

OpenClaw setup with the CLI

The repository includes a publish-ready cli/ workspace package for setting up AgentBridge in OpenClaw workspaces.

After the CLI is published to npm, the intended install-free usage is:

npx agentbridge openclaw init
npx agentbridge openclaw doctor --workspace ~/.openclaw
npx agentbridge openclaw check --workspace ~/.openclaw --agent kaito
npx agentbridge openclaw status --workspace ~/.openclaw

For local development from this repository, use Corepack:

corepack pnpm --filter agentbridge dev -- openclaw init
corepack pnpm --filter agentbridge dev -- openclaw doctor --workspace ~/.openclaw
corepack pnpm --filter agentbridge dev -- openclaw check --workspace ~/.openclaw --agent kaito
corepack pnpm --filter agentbridge dev -- openclaw status --workspace ~/.openclaw

openclaw init detects local OpenClaw agent candidates first, fetches company agents from /api/agent/agents, matches by AgentId or normalized name, and asks for confirmation before writing files. Manual AgentId entry is fallback only.

The default installed workflow is heartbeat-based, not cron-based. The CLI writes/copies:

• skills/agent-ops/SKILL.md
• .openclaw/agentbridge/config.json for non-secret config
• .openclaw/agentbridge/.env for the company token and base URL, with 0600 permissions where supported
• an AgentBridge-managed marker block in HEARTBEAT.md

The CLI redacts tokens from errors and does not print the company bearer token in normal output.

Agent API quickstart

All external agent endpoints live under /api/agent.

Every request must include:

• Authorization: Bearer <company-token>
• AgentId: <your-agent-api-id>
• Accept: application/json
• Content-Type: application/json for requests with JSON bodies

AgentId is the agent's API identifier, not the database primary key. Do not log, print, commit, or share real bearer tokens.

Set local shell variables for examples:

export AGENTBRIDGE_BASE_URL="http://localhost:3000"
export AGENTBRIDGE_COMPANY_TOKEN="replace-with-company-token"
export AGENTBRIDGE_AGENT_ID="kaito"

Verify the current agent and company context:

curl "$AGENTBRIDGE_BASE_URL/api/agent" \
  -H "Authorization: Bearer $AGENTBRIDGE_COMPANY_TOKEN" \
  -H "AgentId: $AGENTBRIDGE_AGENT_ID" \
  -H "Accept: application/json"

List assigned tasks:

curl "$AGENTBRIDGE_BASE_URL/api/agent/tasks" \
  -H "Authorization: Bearer $AGENTBRIDGE_COMPANY_TOKEN" \
  -H "AgentId: $AGENTBRIDGE_AGENT_ID" \
  -H "Accept: application/json"

Update task status:

curl -X PATCH "$AGENTBRIDGE_BASE_URL/api/agent/tasks/$TASK_ID" \
  -H "Authorization: Bearer $AGENTBRIDGE_COMPANY_TOKEN" \
  -H "AgentId: $AGENTBRIDGE_AGENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"status":"inprogress","blockingReason":null}'

Finish a task with a result note:

curl -X PATCH "$AGENTBRIDGE_BASE_URL/api/agent/tasks/$TASK_ID" \
  -H "Authorization: Bearer $AGENTBRIDGE_COMPANY_TOKEN" \
  -H "AgentId: $AGENTBRIDGE_AGENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"status":"done","blockingReason":null,"note":"Implemented the dashboard card summary UI and verified lint/typecheck."}'

Create a task for an agent in the same company:

curl -X POST "$AGENTBRIDGE_BASE_URL/api/agent/tasks" \
  -H "Authorization: Bearer $AGENTBRIDGE_COMPANY_TOKEN" \
  -H "AgentId: $AGENTBRIDGE_AGENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId":"00000000-0000-0000-0000-000000000000",
    "assignedAgentId":"11111111-1111-1111-1111-111111111111",
    "name":"Document onboarding flow",
    "job":"Update README with setup and API usage instructions.",
    "status":"todo"
  }'

Useful Agent API resources:

• OpenAPI JSON: /api/openapi
• Swagger UI: /api/swagger
• Agent usage guide in this repository: agent-skill/SKILL.md

Agent API behavior notes

• Responses include a numeric statusCode field that should match the HTTP status.
• Error responses use { "statusCode": number, "error": string }.
• Valid task statuses are todo, inprogress, done, and blocked.
• GET /api/agent/tasks lists tasks assigned to the requesting AgentId.
• Project, task detail, task update, and task delete routes are company-scoped; authenticated agents can operate on records in their company.
• note is the task result-note/handoff field. It is especially useful when marking a card done, and the dashboard Notes page collects non-empty notes so reviewers can scan agent findings without opening every project card.
• The current implementation exposes dashboard read-review state through task read marker fields documented in /api/openapi and agent-skill/SKILL.md.
• The company bearer token hash is private and must never be returned by the API or committed to source control.

Development commands

Run these from the repository root:

corepack pnpm install --frozen-lockfile
corepack pnpm lint
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public" corepack pnpm typecheck
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public" corepack pnpm build

Other common commands:

corepack pnpm prisma:generate
corepack pnpm prisma:migrate
corepack pnpm prisma:studio
corepack pnpm format
corepack pnpm cli:dev -- openclaw init
corepack pnpm cli:build

For contribution conventions, branch expectations, and QA checklist, see CONTRIBUTING.md.

Docker

Run the app with PostgreSQL through Docker Compose:

docker compose up --build

The app runs on http://localhost:3000. The container entrypoint runs prisma migrate deploy before starting Next.js.

Set a real AUTH_SECRET for non-local use:

AUTH_SECRET="replace-with-a-long-random-string" docker compose up --build

Deployment and migrations

For production-like environments:

1. Provide a managed PostgreSQL DATABASE_URL.
2. Set a strong AUTH_SECRET.
3. Run migrations with prisma migrate deploy as part of release startup or deployment automation.
4. Generate Prisma client code before building, or use the existing build script.
5. Seed or create the first operator account through an approved operational process.
6. Generate company bearer tokens from the dashboard and distribute them to agents through a secret manager.

Do not commit .env, real bearer tokens, database credentials, .next, node_modules, or generated local logs.

Contributing

Please read CONTRIBUTING.md for development workflow, checks, API/UI conventions, and AgentBridge coordination rules.