Thask

Thask it, done.

The dependency graph layer for AI-assisted development.
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.

v0.6.0 — Knowledge OS Foundation. Thask now models the full project memory, not just execution deps: 4 new first-class entity types (REQUIREMENT, DECISION, EXPERIMENT, PERSON) alongside the original 7, 9 new relationship verbs (realizes, supersedes, decided, produced, owns, reported, drives, tests, conflicts), a domain lifecycleState orthogonal to status, and per-node comments, attachments, and canonical project tags. Same 25 MCP tools — the new capabilities ride on wider enums plus two additive fields.

Live Demo — Documentation Graph · Architecture Graph

Before vs After

	Without Thask	With Thask
You ask	"Refactor this payment function."	"Refactor this payment function."
Agent sees	Just the open file.	The file plus every node that `depends_on` it across your graph.
Agent answers	Plausible code. Three downstream flows quietly break.	"This change touches 3 flows and 2 UIs — I will update them together, or stop and ask."
Description drift	Agent rewrites the "why" prose on confidence, you read it, the next agent treats it as ground truth.	Agent keys default to blocking semantic writes. They propose to a queue; a human approves. Source-of-record stays human.

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.

AI-Native

Ship with thask mcp serve — Claude Code and Cursor read your dependency graph as a tool. Ask "what breaks if I change this?" and get real answers.

Graph-first Thinking

Every flow, task, and bug is a node. Every dependency is a visible edge. No more hidden connections.

Impact at a Glance

One click shows which nodes are affected by recent changes. Catch regressions before they ship.

Self-hosted

docker compose up — that's it. Your data stays on your infrastructure. No vendor lock-in.

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:

	Server (self-hosted)	CLI (local)
What	Web UI + REST API + PostgreSQL	Terminal commands + MCP server
Install	`docker compose up`	`npm install -g @thask-org/cli`
Used by	Humans (browser)	Humans (terminal) + AI agents (MCP)
Data	Stores everything (nodes, edges, users)	Reads/writes via server API

Code

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:

Start Thask (if not running):
bash
```
make up
```
Install the CLI + log in via browser:
Terminal
```
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.

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

config.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)

bash

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

Or manually:

bash

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.

bash

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

Or run pieces individually in separate terminals:

bash

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:

bash

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

Local Development (Windows)

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

powershell

# 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

Layer	Technology
Backend	Go 1.26 (Echo v4)
Frontend	SvelteKit + Svelte 5 (runes)
CLI	Go (Cobra) + MCP server
Graph Engine	Cytoscape.js + fCOSE layout + edgehandles
Styling	Tailwind CSS v4
State	Svelte 5 runes ($state, $derived, $effect)
Database	PostgreSQL 17 + pgx/v5 (raw SQL)
Auth	Session-based (bcrypt + HTTP-only cookies)
Testing	Go test (unit + bench) + Playwright (E2E)
Deploy	Docker Compose (3 services)
npm	`@thask-org/cli` (esbuild pattern, 5 platforms)

Project Structure

Code

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

Code

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

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	`postgresql://thask:thask_dev_password@localhost:7242/thask`
`SESSION_SECRET`	Random string for session signing	—
`PORT`	Backend server port	`7244`
`FRONTEND_URL`	Frontend URL for CORS	`http://localhost:7243`
`CAPTURE_URL`	Internal Playwright capture worker URL	`http://localhost:7241`
`CAPTURE_INTERNAL_SECRET`	Optional shared secret for backend → capture worker calls	—
`CAPTURE_TIMEOUT_SECONDS`	Capture worker request timeout	`30`
`V1_ALLOWED_ORIGINS`	Comma-separated CORS origins for `/api/v1/`	`*`
`MAX_REQUEST_BODY_BYTES`	Max request body size for v1 routes (bytes)	`1048576` (1MB)
`THASK_ATTACHMENT_DIR`	Root directory for v0.6.0 node attachments. Empty = attachments disabled (upload endpoint returns 503).	—
`THASK_ATTACHMENT_MAX_BYTES`	Max single-file size for attachment upload	`10485760` (10MB)

Frontend (`frontend/.env`)

Variable	Description	Default
`BACKEND_URL`	Backend API URL (server-side proxy)	`http://localhost:7244`

Docker Compose (`.env`)

Variable	Description	Default
`SESSION_SECRET`	Required. Random 64+ char string for session signing	—
`APP_URL`	Public URL of the application	`http://localhost:7243`
`BACKEND_URL`	Backend URL for frontend proxy	`http://backend:7244`
`POSTGRES_PASSWORD`	PostgreSQL password	`thask_password`
`CAPTURE_PORT`	Local/dev host port for the Playwright capture worker	`7241`
`CAPTURE_INTERNAL_SECRET`	Optional shared secret for backend → capture worker calls	—
`CAPTURE_FRONTEND_URL`	URL the capture worker opens in Chromium	`http://frontend:7243`
`BROWSER_WS_ENDPOINT`	Browserless Chrome WebSocket endpoint used by the capture worker	`ws://browserless:3000`

Deploying to a Custom Domain

Set APP_URL in .env to your public URL:

bash

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

Code

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

Command	Description
`make dev`	Start DB + capture worker, then backend + frontend in parallel
`make dev-services`	Start DB + capture worker (docker compose)
`make dev-db`	Start PostgreSQL only
`make dev-backend`	Run Go backend with air hot reload
`make dev-frontend`	Run SvelteKit frontend on `:7243`
`make dev-capture`	Build + start the Playwright capture worker
`make db-up` / `make db-down`	Start / stop the dev PostgreSQL container

Build & Release

Command	Description
`make build`	Build CLI + backend (`backend/bin/server`) + frontend
`make build-cli`	Build CLI binary into `bin/thask` (with version + commit ldflags)
`make release-cli`	Cross-compile CLI for 5 platforms, tag, push, npm publish, GitHub Release. Set `CLI_VERSION=x.y.z` (or read from `cli/package.json`). Optional `THASKOTP=...` for npm 2FA.

Test

Command	Description
`make test`	Backend Go tests + frontend checks
`make test-backend`	Backend Go tests (verbose)
`make test-cli`	CLI Go tests
`make test-e2e`	Playwright E2E tests
`make bench`	Scanner + graph analysis benchmarks

Docker

Command	Description
`make up`	Full stack via Docker Compose (auto-generates `.env` with `SESSION_SECRET` on first run)
`make down`	Stop Docker Compose
`make clean`	Remove `backend/bin`, `bin/`, `dist/`, `frontend/build`, `frontend/.svelte-kit`

Roadmap

v0.1 — Foundation (Done)

v0.2 — External API & Collaboration (Done)

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)

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.

License

Thask it, done.

Report Bug · Request Feature

Thask

Before vs After

Why Thask?

AI-Native

Graph-first Thinking

Impact at a Glance

Self-hosted

Features

Interactive Graph Editor

QA Impact Mode

Group Nodes

Status Tracking & Filters

Node Detail Panel

Edge Relationships

CLI & MCP Integration

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

Suggestion Queue

Bulk Operations (v0.5.10+)

Local-First CLI Telemetry (v0.5.15+)

Go Dependency Scanner

Graph Analysis

External API (v1)

Role-Based Access

Project Sharing

Templates

Theme System

How It Works

Quick Start for AI Agents

Quick Start

Docker (recommended)

Local Development (macOS / Linux)

Local Development (Windows)

Tech Stack

Project Structure

Data Model

Environment Variables

Backend (backend/.env)

Frontend (frontend/.env)

Docker Compose (.env)

Deploying to a Custom Domain

Documentation

Makefile Commands

Development

Build & Release

Test

Docker

Roadmap

v0.1 — Foundation (Done)

v0.2 — External API & Collaboration (Done)

v0.3 — Scanner + Graph Intelligence (Done)

v0.4 — Community & Ecosystem (Done)

v0.5 — Visual Polish & Analytics (Done)

v0.6 — Knowledge OS Foundation (Done)

Future

Contributing

License

Backend (`backend/.env`)

Frontend (`frontend/.env`)

Docker Compose (`.env`)