hermes-kanban 1.0.0

Lightweight Kanban board for Hermes Agent

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:

Variable	Default	Description
KANBAN_PORT	9120	Server port
KANBAN_HOST	0.0.0.0	Bind address
KANBAN_AUTH_USER	hermes	Login username
KANBAN_AUTH_PASS	hermes	Login password
KANBAN_NO_AUTH	0	Set to 1 to disable auth
KANBAN_DB	auto	Custom database path
TELEGRAM_BOT_TOKEN	—	Telegram bot token (optional)
TELEGRAM_HOME_CHANNEL	—	Telegram chat ID (optional)

REST API

Method	Endpoint	Description
GET	/api/tasks	List all tasks
GET	/api/tasks/<id>	Get task details
POST	/api/tasks	Create a task
PUT	/api/tasks/<id>	Update a task
PUT	/api/tasks/<id>/status	Change task status
DELETE	/api/tasks/<id>	Delete a task
GET	/api/stats	Task counts by status
GET	/api/agents	Agent workload
GET	/api/agents/config	Auto-detected agents
POST	/api/agents	Add a custom agent
DELETE	/api/agents/<name>	Remove a custom agent
POST	/api/tasks/<id>/comments	Add a comment

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