task-master/README.md

task-master

Offline-first Terminal-Taskmanager (tm) — Kanban-Board, Markdown-Tickets, Checklisten, Zeiterfassung und Reports. Gebaut mit Bubble Tea. Dazu der optionale Web-Server tm_server mit Svelte-UI und SQLite.

Demo wird aus demo.tape erzeugt (make demo). Ohne GIF lokal: siehe Demo aufnehmen.

Features

TUI (tm)

• Projekte & Tickets lokal als JSON hinter einem Hintergrund-Daemon (Unix-Socket)
• Mehrere TUI-Instanzen teilen denselben State; tm stop beendet den Daemon
• Board-Filter: All / Backlog / In Progress / Done
• Tickets in $EDITOR bearbeiten (Markdown + Checklisten)
• Timer, manuelle Zeitbuchungen, Zeiteinträge inkl. Start/Ende editieren
• Report mit Group-by (Ticket / Tag)
• Undo / Redo über eine Command-History (im Daemon)
• Vim-Style Keybindings
• YouTrack Pull/Push (manuell; Remote-URL, Token, Project-Key pro Projekt)
• Sync gegen tm_server (Backend taskmaster, Projekt-Tokens)
• MCP-Token pro Projekt erzeugen (g in der Projektliste) für späteren KI-Zugriff

Web (tm_server)

• Eingebettetes Svelte-UI, SQLite, Auth und Rechte pro Projekt
• Projektgruppen, Sidebar-Navigation, Hash-Routes
• Drag & Drop auf dem Board (OPEN / WIP / DONE)
• Lesbare Ticket-Keys aus Projektcode + Sequenz (z. B. WEB-12)
• Visual- und Markdown-Editor für Ticket-Beschreibungen
• Datei-Anhänge; Tabellen (XLSX/ODS/…) im Browser editierbar
• Report mit Datums- und Ticket-Filtern sowie Eintragsliste
• Sync-Backend pro Projekt, Projekt-Tokens für die TUI, Ticket-Revisionen
• Members, Settings (Tokens), Users (Admin)

Install

Voraussetzung: Go (siehe go.mod). Für tm_server zusätzlich Node.js (Frontend-Build).

git clone git@git.aloxdrim.de:skruecken/task-master.git
cd task-master
make install          # → $(go env GOPATH)/bin/tm
# oder nur bauen:
make build            # → ./bin/tm
make build-server     # Frontend + → ./bin/tm_server
make build-all        # beides

Nutzung

tm                    # TUI starten (startet Daemon bei Bedarf)
tm sync pull          # Issues von YouTrack / tm_server holen
tm sync push          # lokale Änderungen pushen
tm sync pull -p inbox # anderes Projekt
tm status             # Daemon-Status + Socket-Pfad
tm stop               # Hintergrund-Daemon beenden
tm daemon             # Daemon im Vordergrund (Debug)
tm version            # Build-Version (Git-Hash)
tm help

Lokaler JSON-Daemon

tm speichert weiterhin JSON unter dem DataDir, schreibt aber nur noch über einen lokalen Daemon-Prozess (eine Instanz pro DataDir). Socket/PID liegen unter $XDG_RUNTIME_DIR/task-master-<hash>/ (Fallback: Temp-Dir). Die TUI und tm sync verbinden sich als vertrauenswürdige Clients (X-TM-Client: tui|cli).

MCP (tm mcp)

1. In der TUI-Projektliste g → Token erzeugen (Klartext einmal in der Statuszeile); G widerruft.
2. Im Repo-Root (oder darüber) .tm_token anlegen — nicht committen:

project=inbox
token=tm_mcp_…

3. Cursor / MCP-Client:

{ "command": "tm", "args": ["mcp"] }

Ohne gültiges .tm_token macht der MCP-Server keine Daemon-Aufrufe. Mit Token sind Lesen und Schreiben nur für dieses eine TM-Projekt erlaubt.

Web-Server (tm_server)

# Dev/Test gegen lokales tm_server (kein YouTrack): seedet Projekte + verdrahtet TUI
make run-server-dev   # :8080, Data unter ./.dev-home, Login admin/admin
make run-dev          # TUI: Projekte „Test“ + „Website Relaunch“ schon mit Token connected

# Produktion / manuell:
export TM_ADMIN_USER=admin
export TM_ADMIN_PASSWORD='change-me'
export TASK_MASTER_SECRET='long-random-secret'   # verschlüsselt Remote-Tokens
./bin/tm_server -listen :8080

# JSON-Daten der TUI einmalig importieren:
./bin/tm_server import-json -owner admin

UI: http://localhost:8080 — Dashboard, Board, Report, Attachments, Members, Settings (Tokens), Users (Admin), Ticket-Zeit & History.

Das Test-Environment (run-server-dev) spricht nur mit diesem Backend; YouTrack ist dort nicht verdrahtet.
Beim Seed (TM_SEED_DEMO=1) werden Demo-Projekte angelegt und für Test sowie Website Relaunch Write-Tokens unter .dev-home als lokale TUI-Projekte (backend=taskmaster) hinterlegt — danach make run-dev und Sync (Y → Pull). Login: admin/admin (Member: alice/alice).

Dev-Frontend (Vite, API-Proxy): cd web && npm run dev parallel zu tm_server. Frontend neu bauen ohne Go-Rebuild: make web-build.

Sandbox ohne echte Config/Daten:

make run-dev          # nutzt ./.dev-home
# oder:
TASK_MASTER_HOME=/tmp/tm-sandbox tm

Daten landen standardmäßig unter ~/.local/share/task-master, Config unter ~/.config/task-master.

Variable	Wirkung
TASK_MASTER_HOME	Basis für Config + Daten (Dev/Demo)
TASK_MASTER_DATA_DIR	Nur Datenverzeichnis überschreiben
TASK_MASTER_SECRET	Verschlüsselt Remote-Tokens in SQLite
TM_ADMIN_USER / TM_ADMIN_PASSWORD	Bootstrap des ersten Admins
TM_SEED_DEMO=1	Demo-Projekte + TUI-Verdrahtung (Test / Website Relaunch)
TM_SEED_BASE_URL	Basis-URL in den geseedeten TUI-meta.json

Server-Flags: -listen, -db, -secure (siehe tm_server help).

Keybindings (Auszug)

Taste	Aktion
j/k	Navigieren
n	Neues Ticket/Projekt
e	Ticket bzw. Projekt editieren (in Projektliste: YouTrack / Sync-Backend)
s	Status ändern
l	Board-Filter
/	Suche
p/P	Projekt / Ticket verschieben
Y	Sync-Menü: Pull / Push
t/T	Timer / Zeit buchen
m	Zeiteinträge
r	Report
x/X	Löschen / Force-Delete
u/U	Undo / Redo
q	Beenden

Checklisten im Preview: J/K + Space.

YouTrack / Sync

1. p → Projekt wählen → e
2. Backend wählen: YouTrack (Remote-URL, Permanent Token, Project-Key) oder task-master (Server-URL + Projekt-Token)
3. Lokal arbeiten (Anlegen/Edit/Status bleiben lokal)
4. Y → Pull oder Push
   CLI: tm sync pull / tm sync push

Zeit: lokale Einträge ohne externalId werden remote als Work-Items gepusht; remote Work Items landen lokal beim Pull.

Status-Mapping Richtung YouTrack: OPEN→Open, WIP→In Progress, DONE→Fixed (Workflow-Namen können projektspezifisch abweichen).

Entwicklung

make test
make build
make build-server   # braucht Node (npm ci + Vite-Build)
make version

CI (Gitea): Tests, tm + tm_server-Build, Demo-GIF als Artifact.

Demo aufnehmen

Die Walkthrough-Aufnahme steckt in demo.tape (VHS):

# einmalig: vhs + ttyd/ffmpeg (siehe VHS-Docs)
make demo             # schreibt demo.gif (+ demo.mp4)

Die Pipeline erzeugt das GIF ebenfalls und lädt es als Artifact hoch.

Lizenz

Privat / eigener Use — siehe Repository-Einstellungen auf Gitea.