---

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):

   make up
   

2. Install the CLI + log in via browser:

   npm install -g @thask-org/cli
   thask config set url http://localhost:7244
   thask 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):

   {
     "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 PostgreSQL
docker compose -f docker-compose.dev.yml up -d

# Terminal 2 — Start backend
cd backend
copy .env.example .env
go run ./cmd/server

# Terminal 3 — Start frontend
cd frontend
copy .env.example .env
npm install
npm 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:

# .env
APP_URL=https://thask.example.com
SESSION_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.

---