hermes-kanban-miniapp/README.md

Hermes Kanban Mini App

Telegram Mini App and web dashboard for Hermes Agent Kanban boards. View, create, and manage tasks from mobile or desktop.

Русская версия

What it does

• Board view: Kanban columns — triage, todo, ready, running, blocked, done, archived
• Task details: body, events, runs, log tail, comments
• Task actions: create, assign, promote, block/unblock, archive, dispatch, comment
• Telegram integration: Mini App theme variables, initData auth, haptic feedback
• Secure bridge: execFile with shell: false, command allowlist, token auth

Architecture

Telegram Mini App / Browser
        │
        │  HTTPS / Vite proxy in dev
        ▼
React + TypeScript + Vite frontend  (port 5173 dev / 80 nginx)
        │
        │  /bridge/v1/*  (X-Bridge-Token or dev mode)
        ▼
Express Bridge  (port 3456)
        │
        │  hermes kanban ... --json  (execFile, shell: false)
        ▼
Hermes Kanban board (SQLite)

Monorepo structure (pnpm workspace):

• packages/contracts — shared TypeScript types + Zod schemas
• packages/bridge — Express API server, CLI wrapper
• frontend — React + Vite SPA with Tailwind CSS

Quick start

Prerequisites

• Node.js ≥ 18
• pnpm 9.x (corepack enable)
• Hermes Agent installed with Kanban enabled

Local development

git clone https://github.com/Kisskin-Mister/hermes-kanban-miniapp.git
cd hermes-kanban-miniapp
cp .env.example .env          # edit as needed
pnpm install
make dev                       # starts bridge + frontend

• Frontend: http://localhost:5173 (Vite dev server with hot reload)
• Bridge API: http://localhost:3456/bridge/v1/health

Docker Compose

cp .env.example .env           # edit HERMES_HOME, BRIDGE_TOKEN, etc.
make docker-build              # or: docker compose build
make up                        # or: docker compose up -d

• Frontend: http://localhost:8080
• Bridge API: http://localhost:3456 (internal, proxied by nginx)

Production

make build                     # build TypeScript
make docker-build              # build images
make up                        # start containers

The docker-compose.yml mounts ~/.hermes read-only into the bridge container. Configure HERMES_HOME in .env.

Environment variables

Bridge (.env)

Variable	Default	Description
BRIDGE_HOST	127.0.0.1	Bridge bind address
BRIDGE_PORT	8787	Bridge port
BRIDGE_TOKEN	—	Auth token (X-Bridge-Token header)
AUTH_MODE	token	token (validate header) or dev (bypass auth)
BRIDGE_ALLOWED_BOARDS	default	Comma-separated board slugs or *
COMMAND_TIMEOUT_SECONDS	30	Per-command timeout
LOG_TAIL_MAX_LINES	500	Max log lines returned
HERMES_BIN	hermes	Path to hermes executable
HERMES_HOME	—	Hermes profile directory
TELEGRAM_BOT_TOKEN	—	For initData validation (optional)

Docker Compose

Variable	Default	Description
HERMES_HOME	/home/kisskin/.hermes	Mounted into bridge container

Makefile commands

make install       — pnpm install
make dev           — run bridge + frontend in dev mode
make build         — build all TypeScript packages
make typecheck     — run TypeScript type checking
make test          — run bridge tests
make ci            — install + typecheck + test + build
make docker-build  — build Docker images
make up            — docker compose up -d
make down          — docker compose down
make logs          — follow service logs
make clean         — remove build artifacts

Telegram Mini App setup

1. Create a bot with BotFather
2. Set the Mini App domain: /setdomain → your HTTPS domain
3. Configure .env:

   AUTH_MODE=token
   BRIDGE_TOKEN=<generate-a-strong-token>
   TELEGRAM_BOT_TOKEN=<your-bot-token>
   

4. Deploy with HTTPS (Caddy, Nginx, Traefik, or Cloudflare Tunnel)

CI

Forgejo CI workflow (.forgejo/workflows/test.yml) runs on push to main:

• Typecheck contracts, bridge, frontend
• Run bridge unit tests (vitest)
• Build frontend

License

MIT — see LICENSE.

---

Hermes Kanban Mini App / На русском

Telegram Mini App и веб-панель для управления задачами Hermes Agent. Просматривайте, создавайте и управляйте задачами с мобильного или десктопа.

Что это

• Доска с колонками: triage, todo, ready, running, blocked, done, archived
• Детали задачи: описание, события, запуски, логи, комментарии
• Действия: создание, назначение, продвижение, блокировка/разблокировка, архивация, диспетчеризация
• Интеграция с Telegram: темы Mini App, авторизация initData, тактильная обратная связь

Быстрый старт

Локальная разработка

git clone https://github.com/Kisskin-Mister/hermes-kanban-miniapp.git
cd hermes-kanban-miniapp
cp .env.example .env
pnpm install
make dev

• Фронтенд: http://localhost:5173
• API моста: http://localhost:3456/bridge/v1/health

Docker Compose

cp .env.example .env
# Отредактируйте HERMES_HOME, BRIDGE_TOKEN и другие переменные
make docker-build
make up

• Фронтенд: http://localhost:8080
• Мост (внутренний): http://localhost:3456

Предварительные требования

• Node.js ≥ 18
• pnpm 9.x (corepack enable)
• Hermes Agent с включённым Kanban

Переменные окружения

Смотрите таблицу выше или файл .env.example.

Команды Makefile

Команда	Описание
make dev	Запуск bridge + frontend в режиме разработки
make build	Сборка всех TypeScript пакетов
make test	Запуск тестов bridge
make docker-build	Сборка Docker образов
make up	Запуск сервисов через docker compose
make down	Остановка сервисов
make ci	Полный CI-пайплайн локально

Установка Telegram Mini App

1. Создайте бота через BotFather
2. Установите домен Mini App: /setdomain → ваш HTTPS домен
3. Настройте .env с AUTH_MODE=token, BRIDGE_TOKEN и TELEGRAM_BOT_TOKEN
4. Разверните с HTTPS (Caddy, Nginx, Traefik, Cloudflare Tunnel)

Лицензия

MIT — см. LICENSE.