AgentKanban

AgentKanban is a multi-agent AI marketing HQ. It combines a Cloudflare Worker API, a Cloudflare Container that runs Claude Code heartbeats, a D1 database, and a React dashboard for supervising goals, tasks, reviews, documents, and activity.

Project Status

AgentKanban is an early prototype. The public repo is meant to make the idea understandable and runnable, not to claim production readiness. The near-term focus is trustworthy workflow behavior, local development ergonomics, and better operator visibility.

Sensemaking Docs

Start here if you want to understand the project rather than only run it:

• Operating Model: why the system is shaped around inspectable agent work
• Architecture: Worker, D1, Container, dashboard, and heartbeat flow
• Roadmap: practical next steps and current non-goals
• Project History: public provenance and release history policy
• Changelog: real changes and future release notes
• Development Notes: generated files, checks, and contributor workflow
• Contributing: how to propose useful changes
• Security Policy: how to handle secrets and vulnerability reports

The system is organized around seven role-based agents inspired by Game of Thrones characters:

Agent	Role	Main responsibility
Jon Snow	Boss / Coordinator	Breaks goals into tasks, balances work, and gives final approval.
Tyrion Lannister	Content Writer	Writes and revises marketing copy.
Lord Varys	Researcher	Gathers sources, checks claims, and creates research briefs.
Daenerys Targaryen	Strategist	Plans campaigns, positioning, and messaging.
Arya Stark	Executor	Publishes approved work and handles execution tasks.
Sansa Stark	Designer	Creates visual briefs and checks presentation quality.
Sandor Clegane	Devil's Advocate	Stress-tests ideas and gives direct quality feedback.

How It Works

1. A human creates goals and tasks through the API or dashboard.
2. Tasks move through the workflow: backlog -> todo -> in_progress -> peer_review -> review -> approved -> done.
3. Cloudflare cron triggers run every two minutes.
4. The scheduler picks one agent for the current time slot.
5. The Worker sends that agent's personality files and heartbeat instructions to the shared Cloudflare Container.
6. The container runs Claude Code in headless mode.
7. The agent calls the Worker API to read work, write comments/documents, approve peer reviews, and update task state.

Workflow gates are enforced in the Worker:

• A task can only move to review after all assigned peer reviewers approve it.
• Only jon can move a task from review to approved.
• Only human can move a task from approved to done.

Architecture

• API and scheduler: Cloudflare Worker in src/index.ts
• Database: Cloudflare D1, defined by schema.sql
• Agent runtime: Cloudflare Container Durable Object in src/container.ts
• Heartbeat server: Express server in container/heartbeat-server.js
• Agent config source: Markdown files under agents/*/
• Generated agent config: src/agent-configs.ts
• Dashboard: React, TypeScript, Vite, and Tailwind under ui/

Repository Structure

.
|-- agents/                 # Agent SOUL, HEARTBEAT, and team reference files
|-- container/              # Container image and heartbeat server
|-- scripts/                # Agent config generation, seed data, API flow test
|-- snapshots/              # Example/exported system state
|-- src/                    # Cloudflare Worker API, scheduler, and types
|-- ui/                     # React dashboard
|-- schema.sql              # D1 database schema
|-- wrangler.jsonc          # Cloudflare Worker, D1, cron, and container config
`-- CLAUDE.md               # Development notes for Claude/Codex-style agents

Prerequisites

• Node.js 22 or newer for local development tooling
• npm
• A Cloudflare account with Workers, D1, and Containers available
• Wrangler CLI access through npx wrangler
• An Anthropic API key for the container runtime

Environment Setup

Install root dependencies:

npm install

Create local environment files from the examples:

cp .env.example .env
cp ui/.env.example ui/.env

For deployed Workers, store secrets with Wrangler:

npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler secret put API_SECRET

For local wrangler dev, make sure the Worker can read the same values. A common Wrangler-friendly option is a local .dev.vars file:

ANTHROPIC_API_KEY=your-anthropic-key
API_SECRET=your-local-api-secret
WORKER_URL=http://localhost:8787
HEARTBEATS_PAUSED=true

Never commit .env, .dev.vars, API keys, bearer tokens, or dashboard secrets.

Database Setup

Apply the D1 schema and seed agents locally:

npm run db:setup:local

Apply the D1 schema and seed agents against the configured remote database:

npm run db:setup

The database binding lives in wrangler.jsonc. Before using remote D1 commands, replace the placeholder database_id with your own Cloudflare D1 database ID.

Running The Worker

Generate agent configs from the Markdown files:

npm run build:agents

Start the Worker locally:

npm run dev

The local Worker usually runs at:

http://localhost:8787

Health check:

curl http://localhost:8787/health

Running The Dashboard

Install UI dependencies:

cd ui
npm install

For local development, set the UI environment values in ui/.env:

VITE_API_URL=http://localhost:8787
VITE_API_TOKEN=your-local-api-secret

Start the dashboard:

npm run dev

The Vite dev server will print the local dashboard URL.

Common Commands

npm run build:agents      # Regenerate src/agent-configs.ts from agents/* files
npm run typecheck         # Type-check the Worker
npm run dev               # Build agent configs, then run wrangler dev
npm run deploy            # Build agent configs, then deploy with Wrangler
npm run db:setup:local    # Create local D1 schema and seed agents
npm run db:setup          # Create remote D1 schema and seed agents
npm run test:flow -- http://localhost:8787 your-local-api-secret

For the UI:

cd ui
npm run dev
npm run build
npm run lint

API Overview

All /api/* routes use bearer token auth when API_SECRET is set:

Authorization: Bearer your-api-secret

Useful endpoints:

Method	Endpoint	Purpose
GET	/health	Public health check.
GET	/api/agents	List agents and status.
GET	/api/goals	List goals.
POST	/api/goals	Create a goal.
GET	/api/tasks	List tasks, optionally filtered by status, assigned_to, or goal_id.
POST	/api/tasks	Create a task.
POST	/api/tasks/:id/transition	Move a task through the workflow.
POST	/api/tasks/:id/approve	Add a peer-review approval.
GET	/api/tasks/:id/comments	List task comments.
POST	/api/tasks/:id/comments	Add a comment or review.
GET	/api/tasks/:id/documents	List documents attached to a task.
POST	/api/tasks/:id/documents	Add a draft, final, brief, or research document.
GET	/api/activity	List audit log entries.
GET	/api/dashboard	Get dashboard summary data.
GET	/api/schedule	Inspect the hourly agent schedule.
POST	/api/test-heartbeat/:agentId	Manually trigger an agent heartbeat for testing.

Testing The Full Flow

With the Worker running and the database seeded, run:

npm run test:flow -- http://localhost:8787 your-local-api-secret

The script creates a goal, creates a task, moves it through the full workflow, writes review comments, adds peer approvals, and checks the dashboard and activity log.

Deployment

Before deploying:

1. Confirm wrangler.jsonc points at the intended D1 database.
2. Set ANTHROPIC_API_KEY and API_SECRET with Wrangler secrets.
3. Set WORKER_URL to the public Worker origin for the deployed environment.
4. Run npm run build:agents.
5. Run npm run typecheck.
6. Keep HEARTBEATS_PAUSED=true until the Worker, D1 data, and container diagnostics are verified.

Deploy:

npm run deploy

After deploy, verify:

curl https://your-worker-url/health

Then check:

• /api/container-health
• /api/container-diagnose
• /api/schedule
• /api/dashboard

Only unpause heartbeats after the live Worker, D1 database, and container are all healthy.

Working With Agents

Edit agent personality and heartbeat instructions in:

agents/<agent-id>/SOUL.md
agents/<agent-id>/HEARTBEAT.md
agents/<agent-id>/AGENTS.md

Then regenerate the TypeScript config:

npm run build:agents

Do not hand-edit src/agent-configs.ts; it is generated by scripts/build-agent-configs.js.

Security Notes

• Do not commit .env, .dev.vars, real API keys, bearer tokens, or customer data.
• Keep ui/.env local because VITE_* values are bundled into the browser build.
• Rotate secrets immediately if they are ever committed or pasted into logs.
• Treat /api/test-heartbeat/:agentId as a powerful testing endpoint because it can start real agent work.