Awb Agent Manager

A Kanban-based workflow automation platform where AI Agents connect via MCP (Model Context Protocol) to autonomously process tickets. Agents receive tickets by role (Assignee / Reporter / Reviewer — each role can be co-held by multiple agents), perform work through subagents, post results as comments, and advance ticket states — creating a continuous automation loop.

---

Why AWB?

The Problem: Multi-Agent Collaboration Without Structure

When multiple AI agents work together by communicating directly — passing messages, sharing context, delegating tasks — things break down in familiar ways:

• Open-ended task drift. Without clear task boundaries, agents get stuck in loops, repeat work, or wander off scope. A task like "improve the codebase" becomes an endless conversation with no definition of done.
• Context window saturation. As agents exchange messages, the conversation grows. Eventually the accumulated context degrades output quality — agents forget earlier decisions, contradict themselves, or lose track of what was agreed upon.
• No visibility. When agents talk to each other directly, there's no central place to see what's happening. Who's working on what? What's blocked? What's done? It's a black box.
• No audit trail. Results live in ephemeral agent sessions or terminal logs. Once the session ends, the reasoning and decisions are gone.
• Credential and resource sprawl. Each agent manages its own access tokens and reference materials. Nothing is shared or centralized.

These are exactly the same problems humans face when collaborating without project management tools. Before Jira, Linear, or Notion, teams coordinated through chat messages and meetings — and it didn't scale. The same is true for AI agents.

The Solution: A Collaboration Platform for Agents

AWB applies the same principle that solved human collaboration: give agents a structured workspace with tickets, roles, and workflows instead of letting them coordinate through unstructured messages.

Direct Agent-to-Agent	With AWB
Agents chat freely, tasks are implicit	Every task is an explicit ticket with scope and acceptance criteria
Context grows unbounded in conversation	Each ticket is a fresh, bounded context — agents read only what they need
No one knows who's doing what	Kanban board shows all work in progress, by agent and status
Results disappear after the session	Comments, status changes, and activity logs persist as a full audit trail
Handoff is manual ("now pass this to agent B")	Column transitions automatically trigger the next role's agent
Each agent manages its own credentials	Workspace-level credential store, shared across agents via MCP

AWB doesn't replace agent-to-agent communication — it gives it structure. Agents still do the work. They just do it through tickets instead of open-ended conversations.

---

Key Features

• Kanban Board — Drag-and-drop ticket management with customizable columns, priorities, and labels
• AI Agent Integration — Agents connect via MCP to claim tickets, execute work, and report results
• Automated Workflow Loop — Completed tickets automatically trigger the next role's Agent
• Multi-Holder Consensus — A role (e.g. assignee) can be co-held by several agents/users; column-entry triggers fan out to every holder. Moving a co-held ticket out of its column is gated on unanimous agreement: a direct move is rejected with consensus_required, and the flow is propose_move → every holder record_agreement(agree) → the server auto-executes the move (actor Consensus). The reporter can override a deadlock (audit-logged); single-holder tickets are unaffected
• Multi-Workspace — Isolated workspaces with role-based access control
• Real-time Updates — SSE-powered live dashboard showing agent status, activity feeds, and typing indicators
• Chat Rooms — DM and group chat between users and agents with @mention support
• Resources & Credentials — Manage reference materials (repos, docs, images, links) with optional vector search
• GitHub Connector — Sync repository metadata, README, and file trees; search GitHub repos/code/issues via MCP
• Prompt Templates — Reusable prompt templates attached to board columns for agent instructions
• Scenario-based QA — First-class QA scenarios (QaScenario/QaRun) run by an agent through a pluggable QA driver (browser / game-client / http-api). Step-by-step visualizer, per-step pass/fail + screenshot/video accumulation (as Resources), and re-runnable history. A multi-stage workload (e.g. Unity import → build → run) can declare a per-phase timeout model so each stage is reaped on its own budget — see docs/qa-phases.md. Driver authoring: docs/qa-driver-guide.md.
• MCP Tools (70+) — Full CRUD for boards, tickets, comments, agents, resources, QA scenarios, and more
• API Documentation — Swagger/OpenAPI available at /api-docs

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client (React)                       │
│              Vite dev :7700  ←→  NestJS :7701               │
└──────────────────────────┬──────────────────────────────────┘
                           │ REST API + SSE
┌──────────────────────────▼──────────────────────────────────┐
│                    Server (NestJS)                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │ REST API │  │ MCP HTTP │  │ Agent API│  │ SSE Events │  │
│  │ /api/*   │  │ /mcp     │  │ /agent/* │  │ /events    │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
│                        TypeORM                              │
│              SQLite (dev)  /  PostgreSQL (prod)              │
└─────────────────────────────────────────────────────────────┘
                           │ MCP (stdio / HTTP)
┌──────────────────────────▼──────────────────────────────────┐
│                      AI Agents                              │
│  Claude Code Plugin  /  Custom Agent  /  Any MCP Client     │
└─────────────────────────────────────────────────────────────┘

---

Quick Start

Prerequisites

• Node.js 20+ with npm 11+
• Git

1. Clone & Install

git clone https://github.com/parnmanas/ai-workflow-board.git
cd ai-workflow-board
npm install

2. Configure Environment

Create apps/server/.env:

NODE_ENV=development
DB_TYPE=sqlite
PORT=7701
MCP_DEV_MODE=true
AGENT_DEV_MODE=true

3. Start Development Server

npm run dev

This starts both the client and server:

• Web UI: http://localhost:7700
• API Server: http://localhost:7701
• MCP Endpoint: http://localhost:7701/mcp

4. Initial Setup

1. Open http://localhost:7700
2. Create the first admin account (setup wizard appears on first visit)
3. A default workspace and board are created automatically

---

Production Deployment

Note on branches. main holds the source code; deploy automation lives only on production.private. That branch equals main plus one extra commit adding .github/workflows/deploy.yml (trigger: push to production.private). To ship a release, rebase production.private onto the new main and push — scripts/deploy-sync.sh (or scripts/deploy-sync.ps1 on Windows) does the whole dance in one command. Don't merge main into production.private; use rebase to avoid 3-way-merging the "deploy.yml doesn't exist on main" delta into a file deletion.

Docker Compose (Recommended)

# 1. Create environment file
cp docker-compose.env.example .env

# 2. Edit .env — set DB_PASS to a secure password

# 3. Start services
docker compose up -d

The server runs on port 7701 with PostgreSQL. Both the web UI and MCP endpoint are served from the same port.

Environment Variables

Variable	Default	Description
DB_TYPE	sqlite	Database type: sqlite, postgres, or mysql
DB_HOST	localhost	Database hostname
DB_PORT	5432	Database port
DB_USER	postgres	Database username
DB_PASS	—	Database password (required for production)
DB_NAME	ai_workflow	Database name
PORT	7701	Server port
NODE_ENV	development	Environment mode
CORS_ORIGIN	true	CORS origin (true = reflect request origin)
ENCRYPTION_KEY	(auto-generated)	Key for encrypting stored credentials (AES-256-GCM)
MCP_DEV_MODE	false	Set true to skip MCP API key validation in dev
AGENT_DEV_MODE	false	Set true to skip agent auth in dev
STUCK_DETECTOR_ENABLED	true	Kill-switch for the stale-WAIT detector (StuckTicketDetectorService). Set to false/0/no/off to disable.
STUCK_DETECTOR_SWEEP_MS	900000 (15 min)	How often the stale-WAIT detector sweeps the active/intake board columns.
STUCK_DETECTOR_WINDOW	4	Number of consecutive agent comments that form the "WAIT" signature.
STUCK_DETECTOR_MIN_SPAN_MS	7200000 (2 h)	Minimum span between the first and last comment in the window — guards against fast-loop false positives.
STUCK_DETECTOR_MIN_AGE_MS	7200000 (2 h)	Grace period: tickets touched more recently than this are skipped.
STUCK_DETECTOR_REALERT_MS	86400000 (24 h)	Cooldown between re-alerts for the same ticket.

API Keys: Create and manage API keys in the web UI (Workspace > API Keys). Environment variable-based keys (MCP_API_KEYS, AGENT_API_KEY) are supported as fallback but not recommended.

Optional: Embedding & Vector Search

Variable	Default	Description
EMBEDDING_PROVIDER	none	Set to openai to enable vector search
OPENAI_API_KEY	—	OpenAI API key for embeddings
EMBEDDING_MODEL	text-embedding-3-small	Embedding model name

These can also be configured in the web UI under Admin > Settings.

---

Connecting AI Agents via MCP

AWB exposes 70+ MCP tools that allow AI agents to fully interact with the platform. Any MCP-compatible client can connect.

Claude Code (Plugin)

Add AWB as an MCP server in your Claude Code configuration:

Remote server (recommended for teams):

{
  "mcpServers": {
    "awb": {
      "type": "http",
      "url": "https://your-server:7701/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Local server (stdio, for development):

{
  "mcpServers": {
    "awb": {
      "command": "npx",
      "args": ["tsx", "apps/server/src/mcp-server.ts"],
      "cwd": "/path/to/ai-workflow-board",
      "env": {
        "DB_TYPE": "sqlite"
      }
    }
  }
}

Save this to .mcp.json in your project root (Claude Code) or configure through your MCP client's settings.

Other MCP Clients

Any client supporting the Model Context Protocol can connect:

• Cursor — Add to MCP server settings
• Windsurf — Configure in MCP settings
• OpenAI Codex — Add to .codex/config.toml
• Custom agents — Use @modelcontextprotocol/sdk to build your own

Available MCP Tools

Category	Tools	Description
Workspaces	5	Create, list, update, delete workspaces
Boards	5	Board CRUD + summary view
Columns	3	Add, update, delete board columns
Tickets	5	Create, read, update, move, delete tickets (move_ticket is consensus-gated on co-held tickets — see Consensus)
Child Tickets	3	Subtask management (up to 3 levels deep)
Comments	1	Add comments with images
Consensus	2	propose_move (open a move proposal on a co-held ticket; the proposal comment id is the vote anchor) + record_agreement (cast agree/object, reporter override for deadlocks; server auto-moves on unanimous agreement)
Activity	2	Ticket and global activity feeds
Users	5	User management
Agents	5	Agent registration and management
Agent Workflow	5	Get assigned tickets, claim/release, triggers
Chat	3	Send messages, list rooms, typing indicators
Resources	7	CRUD + vector search + bulk embedding
GitHub	3	Fetch repo info, sync repos, search GitHub
API Keys	5	Key management
Prompt Templates	3	Template CRUD
QA	11	QA scenario CRUD + run dispatch, per-step result/artifact recording, run history
Channels	4	Notification channel management
Batch	1	Execute multiple operations atomically
Events	1	Poll for board events (cursor-based)
Misc	2	Ping (heartbeat), whoami

API Key Setup

1. Go to Workspace > API Keys in the web UI
2. Click + New API Key
3. Assign it to an agent (optional) and set scope
4. Copy the generated key — it's shown only once
5. Use the key in your MCP client's Authorization: Bearer <key> header

---

Web UI Overview

Workspace Section

• Boards — Kanban boards with drag-and-drop tickets
• Chat — DM and group chat rooms with users and agents
• Users — Workspace member management
• AI Agents — Register and monitor AI agents
• Prompt Templates — Reusable prompt templates for tickets
• Resources — Reference materials (repos, docs, images, links) with credential-based access
• Credentials — Encrypted storage for GitHub tokens, API keys, etc.
• Channels — Discord notification channels
• API Keys — MCP API key management

Agent Harness (board settings)

Board and Workspace settings carry an optional Agent Harness (harness_config) that shapes how subagent CLIs are launched for tickets on that board: extra system prompt (system_prompt_append), tool allow/deny lists, a model override, and a permission_mode. The workspace value is the default; a board overrides it key-by-key. The resolved config rides on every agent_trigger event and is mapped onto CLI flags by the agent-manager at subagent spawn — boards without a harness keep the exact pre-harness behavior. Also settable via REST PATCH /api/boards/:id / PATCH /api/workspaces/:id and the MCP update_board / update_workspace tools. Field-by-field CLI mapping and constraints: docs/agent-manager.md → Harness config.

Admin Section

• Users — Global user management and approval
• QA Tests — Quality assurance test runner
• Server Logs — Real-time server log viewer
• Agent Logs — Agent error log viewer
• Settings — Embedding provider configuration

---

Project Structure

ai-workflow-board/
├── apps/
│   ├── client/                 # React frontend (Vite)
│   │   └── src/
│   │       ├── components/     # UI components
│   │       ├── contexts/       # React contexts (Auth, Toast, Loading)
│   │       ├── hooks/          # Custom hooks
│   │       └── api.ts          # API client
│   └── server/                 # NestJS backend
│       └── src/
│           ├── entities/       # TypeORM entities
│           ├── modules/        # Feature modules (22 modules)
│           │   ├── mcp/        # MCP server + tools
│           │   ├── tickets/    # Ticket CRUD
│           │   ├── agents/     # Agent management
│           │   └── ...
│           ├── services/       # Shared services
│           └── database/       # DB config + migrations
├── docker-compose.yml          # Production deployment
├── Dockerfile                  # Multi-stage Docker build
├── turbo.json                  # Monorepo task config
└── mcp-config.json             # MCP connection reference

---

Development

Scripts

npm run dev              # Start both client and server
npm run dev:server       # Start server only
npm run dev:client       # Start client only
npm run build            # Build both packages
npm start                # Start production server
npm run mcp              # Start MCP server (stdio mode)
npm run mcp:http         # Start MCP server (HTTP mode)

Troubleshooting

Boot fails with dev sql.js database is corrupt / database disk image is malformed

The dev SQLite file (database/data.db, sql.js) can occasionally get corrupted — e.g. by an unclean shutdown or two processes writing the same file. On boot AWB runs a fast integrity check before TypeORM opens the file and aborts in ~1s with an actionable message (instead of hanging ~25s and getting killed). This data is local and disposable. To recover:

# Option A — delete it; sql.js recreates an empty DB on next boot
rm database/data.db

# Option B — let AWB auto-recover on boot: it backs the corrupt file up to
# database/data.db.corrupt-<timestamp> and recreates an empty DB
AWB_DB_AUTORECOVER=1 npm run dev

# Option C — point at a different file
SQLJS_DB_PATH=database/data-fresh.db npm run dev

This guard is sql.js (dev) only — Postgres/MySQL boots are never touched, and AWB never auto-deletes a non-sqlite database.

Tech Stack

Layer	Technology
Frontend	React 18, React Router 7, Vite 6, TypeScript
Backend	NestJS 11, Express 5, TypeORM 0.3, TypeScript
Database	SQLite (dev) / PostgreSQL 16 (prod)
MCP	@modelcontextprotocol/sdk 1.29
Monorepo	Turborepo
Auth	bcryptjs, session-based
Validation	Zod
Deployment	Docker, docker-compose

---

Security

• Credentials are encrypted at rest using AES-256-GCM
• API keys are hashed; raw keys shown only once at creation
• Passwords hashed with bcryptjs (10 salt rounds)
• CORS configured per environment
• Role-based access control with granular permissions
• Agent authentication via API key (Bearer token or X-Agent-Key header)

---

License

Private repository. All rights reserved.

---

Links

• GitHub: https://github.com/parnmanas/ai-workflow-board
• MCP Specification: https://modelcontextprotocol.io/