hermes-kanban

A lightweight, self-contained Kanban board built for Hermes Agent. Zero external dependencies — just SQLite, Flask, and a single pip install.

What is this?

Hermes Kanban gives your AI agents a shared task board. Agents create, update, and complete tasks through a REST API. You monitor everything through a clean web UI with drag-and-drop, dark/light themes, and real-time updates.

Agents are auto-detected from your Hermes profiles — no configuration needed. Install it, start it, and your agents appear automatically.

Quick Start

pip install hermes-kanban
hermes-kanban serve

Open http://localhost:9120 — Login: hermes / hermes

That's it. Your agents from ~/.hermes/profiles/ are already on the board.

Features

• Auto-detect agents — scans ~/.hermes/profiles/ and pulls names + descriptions from SOUL.md
• Dark & Light themes — toggle with one click, respects your preference
• Responsive design — works on desktop and mobile
• Drag & drop — move tasks between columns visually
• SQLite backend — no database server needed, single file storage
• REST API — full CRUD for tasks, agents, and comments
• Telegram notifications — optional, get notified on task changes
• Basic auth — protect your board (configurable)
• Export — download your tasks as JSON anytime

Screenshots

Dark Theme

Light Theme

Mobile

How Agent Detection Works

~/.hermes/profiles/
  kaveh/SOUL.md      → "# Kaveh — Team Lead"
  dariush/SOUL.md    → "# Dariush — Developer"
  emily/SOUL.md      → "# Emily — Friend & Companion"
  yasaman/SOUL.md    → "# Yasaman — QA Engineer"

Hermes Kanban reads each profile folder, extracts the first line of SOUL.md as the display name, and assigns a color. Add a new profile → it appears on the board automatically.

You can also add agents manually via POST /api/agents — these show up with source: "custom".

Configuration

All settings are optional via environment variables:

REST API

Create a task

curl -X POST http://localhost:9120/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix login bug",
    "description": "Users cant login with SSO",
    "assignee": "dariush",
    "priority": 1,
    "status": "todo"
  }'

List agents

curl http://localhost:9120/api/agents/config

[
  {
    "name": "dariush",
    "display_name": "Dariush — Developer",
    "color": "#4f8ee8",
    "source": "hermes"
  }
]

Hermes Integration

Hermes Agent discovers the Kanban board via SQLite. Once the server is running, agents can:

1. Create tasks via POST /api/tasks
2. Update status via PUT /api/tasks/<id>/status
3. Add comments via POST /api/tasks/<id>/comments
4. Check workload via GET /api/agents

Agents see each other's tasks and can pick up work from any column.

Development

git clone https://github.com/2D-Soft/hermes-kanban.git
cd hermes-kanban
pip install -e .
hermes-kanban serve --port 9121

License

MIT