Thask

Before vs After

Every change is recorded with 6-dimension provenance (actor, channel, agent model, mutation kind, trigger, evidence) so the next agent knows what to trust and what to re-derive from code.

Why Thask?

Spreadsheets lose context. Linear issue trackers hide relationships. Thask maps your product as a living graph — so you can see what breaks before it breaks.

Features

Interactive Graph Editor

Drag-and-drop nodes with 11 types — Flow, Branch, Task, Bug, API, UI, Group, plus the v0.6.0 Knowledge OS entities Requirement, Decision, Experiment, and Person. Connect them by hovering and dragging the edge handle. Auto-layout with the fCOSE force-directed algorithm.

QA Impact Mode

Toggle Impact Mode to instantly highlight changed nodes and their downstream dependencies. Dimmed nodes are safe; glowing nodes need attention.

Group Nodes

Organize related nodes into collapsible groups. Drag nodes in and out. Resize groups freely. Double-click to collapse with a child count badge.

Status Tracking & Filters

Track every node as PASS / FAIL / IN_PROGRESS / BLOCKED with color-coded visuals. Filter the graph by node type or status to focus on what matters.

Node Detail Panel

Slide-out panel with full editing — title, description (with markdown rendering), type, status, tags, connected nodes, and a complete change history audit log.

Edge Relationships

Fourteen edge types with distinct colors: the base five (depends_on, blocks, related, parent_child, triggers) plus the v0.6.0 Knowledge OS verbs (realizes, conflicts, drives, supersedes, tests, produced, owns, decided, reported). Every edge also carries a JSONB metadata bag — supersedes records {reason}, produced records {outcome_summary}, etc. Draggable waypoints for edge routing. Click any edge to change its type or delete it.

CLI & MCP Integration

Full CLI for terminal workflows (npm install -g @thask-org/cli). 25 MCP tools for AI agent integration — Claude Code and Cursor can query and modify your graph directly. One-step browser login (thask login), in-place upgrades (thask self-update). CLI Reference · MCP Guide

Per-Key Permissions & Provenance (v0.5.9+)

Every API key is classified as user_interactive, agent, or service with seven independent permission flags. Agent keys default to blocking semantic writes (description, "why" content) and node verification — so a hallucinated description can't silently land on your graph. Every write records 6-dimension provenance (actor, channel, agent model, mutation kind, trigger, evidence) to a single audit_log table. DATABASE.md > Provenance

Suggestion Queue

Agents wanting to revise a description post to node_suggestions and a human approves before the change lands. The deciding human becomes the author of record — the agent is credited only in audit metadata. Server-enforced: accepted decisions require a user_interactive actor regardless of permission flags.

Bulk Operations (v0.5.10+)

Three endpoints cut N round-trips down to one — node.batch_update (up to 200), edge.batch_create / edge.batch_delete (up to 500). Atomic on permission / cycle failure; per-item skip reasons in skipped[]; HTTP 207 Multi-Status when any item skips. Saves substantial agent context (1 call vs N).

Local-First CLI Telemetry (v0.5.15+)

Every CLI invocation, MCP tool call, and HTTP response appends a single JSONL line to ~/.thask/events.jsonl — on your machine only, no upload. Inspect with thask usage (30-day summary, p50/p95 latency, top commands), thask reflog / thask history (recent events, full-text search), or tail -f the file directly. Raw bodies are opt-in (thask telemetry config set capture_payloads true); the default captures only metadata. Tokens, URL credentials, JWT and cookies are masked at write time.

Go Dependency Scanner

Scan Go codebases to auto-generate dependency graphs. thask scan --path . parses go.mod and imports, creating nodes and edges automatically. Extensible via plugin system.

Graph Analysis

Detect dependency cycles (Tarjan DFS) and find the critical path (longest depends_on/blocks chain). Toggle Analysis Mode (Shift+A) to visualize cycles and critical path on the canvas.

External API (v1)

Versioned REST API at /api/v1/ for third-party integrations. OpenAPI 3.1 spec, interactive Scalar docs, structured error responses, and idempotency support. API Guide

Role-Based Access

Four team roles — Owner, Admin, Member, Viewer — with granular permissions. Per-project roles (Editor, Viewer). API key authentication for programmatic access.

Project Sharing

Share projects via link with viewer or editor access. Manage per-project members with granular roles. Public shared views support realtime collaboration. Embeddable graph views and OG image generation.

Templates

Start new projects from built-in templates: API Flow, Microservice Map, Sprint Board. One-click apply from the project creation flow.

Theme System

Light and dark mode with system detection. Persisted per user. Design system uses CSS variables throughout.

How It Works

Thask has two parts:

Browser ──→ Thask Server (Docker) ──→ PostgreSQL                ↑CLI / MCP ──────┘

The server runs your graph database and web UI. The CLI talks to the server's API — you can create nodes, run scans, and analyze graphs from the terminal. AI agents (Claude Code, Cursor) use the CLI's built-in MCP server.

Quick Start for AI Agents

Get Thask working with Claude Code in 2 minutes:

1. Start Thask (if not running):

   bash

   make up

2. Install the CLI + log in via browser:

   bash

   npm install -g @thask-org/clithask config set url http://localhost:7244thask login   # opens browser, click Approve, token saved

   thask login (v0.5.11+) replaces the old "make a key in Settings, copy a 64-char string, paste it" dance. The MCP server reads the same ~/.thask/config.json, so this single login covers Claude Code too. For headless / SSH sessions: create a key in the web UI and run thask config set token <key> instead.

3. Add to Claude Code (.claude/mcp.json):

   json

   {  "mcpServers": {    "thask": {      "command": "thask",      "args": ["mcp", "serve"]    }  }}

Now Claude Code can read and modify your dependency graph — with v0.5.9+ permission gates so agent keys can't silently land hallucinated descriptions. See MCP Guide for details and the official Claude Code plugin for a zero-setup install.

Quick Start

Docker (recommended)

make up   # auto-generates .env with SESSION_SECRET on first run

Or manually:

cp .env.example .env# Edit .env and set SESSION_SECRET (or let make generate it)docker compose up --build

Open http://localhost:7243 and create an account.

Local Development (macOS / Linux)

The Makefile is the source of truth — every dev workflow has a target.

make dev          # one-shot: starts DB + capture worker, then backend + frontend in parallel

Or run pieces individually in separate terminals:

make dev-db       # PostgreSQL only (docker compose)make dev-capture  # Playwright capture worker (docker compose)make dev-backend  # Go backend (requires air: go install github.com/air-verse/air@latest)make dev-frontend # SvelteKit frontend on :7243

If air isn't installed, run the backend directly:

cd backend && cp .env.example .env && go run ./cmd/server

Local Development (Windows)

Prerequisites: Go 1.26+, Node.js 22+, Docker Desktop

# Terminal 1 — Start PostgreSQLdocker compose -f docker-compose.dev.yml up -d
# Terminal 2 — Start backendcd backendcopy .env.example .envgo run ./cmd/server
# Terminal 3 — Start frontendcd frontendcopy .env.example .envnpm installnpm run dev -- --port 7243

Tip: To use make on Windows, install via scoop install make or choco install make.

Open http://localhost:7243

Tech Stack

Project Structure

backend/  cmd/server/           # Go entrypoint, route registration  internal/    config/             # Environment configuration    dto/                # Request/response structs, v1 errors, pagination    handler/            # HTTP handlers (auth, team, node, edge, impact,                        #   graph_analysis, activity, events, og_image, api_key)    middleware/         # Auth, role, project access, shared access,                        #   idempotency, v1 response    model/              # Domain models & enums    repository/         # Database access layer (pgx, 11 repos)    service/            # Business logic (waterfall, impact, graph_analysis,                        #   layout, eventhub, auth)    migrate/            # Migration runner  migrations/           # SQL migration files (001~005)  api/                  # OpenAPI spec + API guide
frontend/  src/    routes/      login/            # Login page      register/         # Register page      dashboard/        # Dashboard & team pages        [teamSlug]/          [projectId]/  # Graph editor page          members/      # Team member management        settings/       # User settings      shared/[shareToken]/  # Public shared view      embed/[shareToken]/   # Embeddable graph      docs/             # Documentation page    lib/      api.ts            # Typed API client      types.ts          # TypeScript type definitions      markdown.ts       # Markdown renderer (marked + DOMPurify)      stores/           # Svelte 5 rune stores (auth, graph, teams,                        #   members, realtime, theme, undo)      components/       # CytoscapeCanvas, GraphToolbar, DetailSidePanel,                        #   MarkdownEditor, ActivityFeed, TemplateSelector,                        #   ShareDialog, SearchBar, ProjectMenu, AddNodeModal      cytoscape/        # Styles, layouts, impact, sync, resize,                        #   portOverlay, groupHelpers, statusDot      managers/         # nodeCrud, edgeCrud  e2e/                  # Playwright E2E tests  static/templates/     # Built-in project templates (3)
cli/  cmd/thask/            # CLI entrypoint  internal/    cmd/                # Cobra commands (node, edge, team, project,                        #   graph, impact, scan, mcp, auth, config,                        #   aliases, install, version)    mcp/                # MCP server (stdio protocol, 12+ tools)    scan/               # Go dependency scanner + plugin runner    client/             # HTTP client for backend API    config/             # Config file management (~/.config/thask/)    output/             # Output formatting (JSON, table, quiet)
npm/                    # npm distribution (@thask-org/cli, 5 platforms)

Data Model

Users ──< TeamMembers >── Teams ──< Projects ──< Nodes ──< NodeHistory  │                                    │            │  └──< ApiKeys                         │            └──< Edges                                       │                                       └──< ProjectMembers >── Users

Node types: FLOW BRANCH TASK BUG API UI GROUP REQUIREMENT DECISION EXPERIMENT PERSON Node statuses: PASS FAIL IN_PROGRESS BLOCKED Node lifecycle state (v0.6.0): free-form text, orthogonal to status. Used for REQUIREMENT/DECISION/EXPERIMENT/PERSON (e.g. APPROVED, RUNNING, DECIDED, ACTIVE). Edge types: depends_on blocks related parent_child triggers realizes conflicts drives supersedes tests produced owns decided reported Side tables (v0.6.0): node_comments, node_attachments, project_tags

Environment Variables

Backend (backend/.env)

Frontend (frontend/.env)

Docker Compose (.env)

Deploying to a Custom Domain

Set APP_URL in .env to your public URL:

# .envAPP_URL=https://thask.example.comSESSION_SECRET=your-random-64-char-string

This configures CORS and CSRF protection automatically. BACKEND_URL does not need to change — the frontend server proxies API requests to the backend over the internal Docker network.

Browser ──https──▶ Reverse Proxy (nginx/Cloudflare)                        │                        ▼ :7243                   Frontend (SvelteKit)                        │                        ▼ http://backend:7244 (Docker internal)                   Backend (Go)                        │                        ▼ http://capture:7241 (Docker internal, optional)                   Capture Worker (Playwright)                        │                        ▼ postgres:5432 (Docker internal)                   PostgreSQL

Place a reverse proxy (e.g. nginx, Caddy, Cloudflare Tunnel) in front to handle SSL termination.

Documentation

• Architecture — Layers, data flow, directory structure
• Database — ER diagram, tables, indexes, relations
• API Reference — 30+ endpoints with request/response examples
• Graph Engine — Node types, edge types, GROUP, impact mode
• Keyboard Shortcuts — All shortcuts and interactions
• CLI Reference — Installation, commands, shell aliases
• MCP Guide — AI agent integration (Claude Code, Cursor)
• Claude Code Plugin — Auto-inject project context + register MCP server in every session
• Scanner Plugins — Scanner plugin system for new languages
• V1 API Guide — External API quickstart for third-party developers

Makefile Commands

The full surface — make is the canonical entrypoint for dev, build, test, and release.

Development

Build & Release

Test

Docker

Roadmap

v0.1 — Foundation (Done)

• Graph CRUD (nodes, edges, groups)
• 7 node types & 4 statuses with visual styling
• fCOSE auto-layout & manual positioning
• Drag-and-drop grouping & compound nodes
• Node search & keyboard shortcuts
• QA impact analysis (BFS-based)
• Status waterfall propagation
• Session-based auth & team management
• Docker Compose one-command deploy
• Go backend with 18 unit tests
• Playwright E2E tests (13 tests)
• CLI tool with full graph operations
• MCP server for AI agent integration (12 tools)
• API key authentication (Bearer token)
• Role-based access control (owner/admin/member/viewer)
• Team member management (invite, roles, transfer)
• Project sharing with public links (viewer/editor modes)
• CLI sharing commands (share, unshare, invite, kick)

v0.2 — External API & Collaboration (Done)

• Real-time collaboration via SSE
• Graph export as PNG / JSON
• Graph import (replace/merge mode)
• Versioned external API (/api/v1/) with OpenAPI spec
• Interactive API docs (Scalar UI at /api/v1/docs)
• Structured error responses for v1
• Idempotency support for API consumers
• CORS configuration for external domains
• Edge waypoints (draggable bend points)
• SVG edge rendering with snap guides
• Embeddable graph views (/embed/:shareToken)
• OG image generation for shared links

v0.3 — Scanner + Graph Intelligence (Done)

• Go dependency scanner (thask scan) with go/ast parsing
• Cycle detection (Tarjan DFS) and critical path analysis
• Analysis Mode frontend (Shift+A toggle, cycles/critical path highlighting)
• MCP tools: thask.scan.run, thask.graph.analyze
• GitHub Actions CI (backend tests, CLI tests, frontend check)
• Scanner plugin system with documentation

v0.4 — Community & Ecosystem (Done)

• npm distribution (@thask-org/cli, 5 platform binaries, esbuild pattern)
• Scanner plugin interface (any executable outputting ImportGraphRequest JSON)
• Homebrew formula template
• Performance benchmarks (scanner + graph analysis)

v0.5 — Visual Polish & Analytics (Done)

• Light/dark theme system with system detection
• Activity feed (recent changes with user attribution)
• Project templates (API Flow, Microservice Map, Sprint Board)
• Amber Precision design system fully applied
• Markdown description rendering (marked + DOMPurify)
• v0.5.6 — Graph image capture (PNG/SVG via Playwright worker)
• v0.5.8 — TypeScript/JavaScript dependency scanner (alias resolution, SvelteKit $lib)
• v0.5.9 — Per-key permissions + suggestion queue + 6-dimension audit_log (anti-hallucination guards)
• v0.5.10 — Bulk endpoints (node.batch_update, edge.batch_*) with HTTP 207 partial-success; thask self-update
• v0.5.11 — thask login browser-based authentication; URL auto-normalization

v0.6 — Knowledge OS Foundation (Done)

• v0.6.0 — 4 new node types (REQUIREMENT, DECISION, EXPERIMENT, PERSON)
• v0.6.0 — 9 new edge verbs (realizes, conflicts, drives, supersedes, tests, produced, owns, decided, reported)
• v0.6.0 — Domain lifecycle state field (orthogonal to status)
• v0.6.0 — Per-edge JSONB metadata
• v0.6.0 — Threaded node comments (node_comments)
• v0.6.0 — Per-node file attachments (node_attachments + THASK_ATTACHMENT_DIR volume)
• v0.6.0 — Canonical project tags (project_tags)
• v0.6.0 — Per-project API key scoping

Future

• Graph version snapshots & diffing
• Node lifecycle analytics (time-in-status, bottleneck detection)
• Webhook triggers on graph changes
• GitHub repo sync (auto-update graph on push)
• Slack / Discord notifications
• Mobile responsive layout
• Self-hosted SSO (SAML / OIDC)

Contributing

We welcome contributions! See CONTRIBUTING.md for setup instructions and guidelines.