hooks— hook

<div align="center">

<table><tr> <td align="center" width="120"><img src="public/icon.svg" alt="Thask" width="80" /></td> <td align="center"><h1>Thask</h1><em>Thask it, done.</em></td> <td align="center" width="160"><img src="public/mascot.png" alt="Thask Mascot" width="140" /></td> </tr></table>

The dependency graph layer for AI-assisted development. <br /> Map what depends on what, then let Claude Code / Cursor / Codex query it through MCP — with provenance guards so agents can't silently land hallucinated descriptions on your graph.

<br />

&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;

<!-- TODO: Add hero screenshot/GIF here -->

Live Demo — Documentation Graph · Architecture Graph

</div>

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.

<table> <tr> <td width="25%" align="center"> <h4>AI-Native</h4> <p>Ship with <code>thask mcp serve</code> — Claude Code and Cursor read your dependency graph as a tool. Ask "what breaks if I change this?" and get real answers.</p> </td> <td width="25%" align="center"> <h4>Graph-first Thinking</h4> <p>Every flow, task, and bug is a node. Every dependency is a visible edge. No more hidden connections.</p> </td> <td width="25%" align="center"> <h4>Impact at a Glance</h4> <p>One click shows which nodes are affected by recent changes. Catch regressions before they ship.</p> </td> <td width="25%" align="center"> <h4>Self-hosted</h4> <p><code>docker compose up</code> — that's it. Your data stays on your infrastructure. No vendor lock-in.</p> </td> </tr> </table>

Features

Interactive Graph Editor

Drag-and-drop nodes with 7 types — Flow, Branch, Task, Bug, API, UI, and Group. 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

Five edge types with distinct colors: depends_on, blocks, related, parent_child, triggers. 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). 24 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

1. 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.

1. 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 Node statuses: PASS FAIL IN_PROGRESS BLOCKED Edge types: depends_on blocks related parent_child triggers

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)

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

v0.2 — External API & Collaboration (Done)

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

v0.3 — Scanner + Graph Intelligence (Done)

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

v0.4 — Community & Ecosystem (Done)

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

v0.5 — Visual Polish & Analytics (Done)

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

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
• [ ] Comment threads on nodes
• [ ] Mobile responsive layout
• [ ] Self-hosted SSO (SAML / OIDC)

Contributing

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

<div align="center">

License

MIT &copy; Thask Contributors

Thask it, done.

Report Bug &middot; Request Feature

</div>