Thask

<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 />

[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
&nbsp;
[![Works with Claude Code](https://img.shields.io/badge/Works_with-Claude_Code-D97706?logo=anthropic&logoColor=white)](docs/CLAUDE_CODE_PLUGIN.md)
&nbsp;
[![Works with Cursor](https://img.shields.io/badge/Works_with-Cursor-000000?logo=cursor&logoColor=white)](docs/MCP.md)
&nbsp;
[![MCP](https://img.shields.io/badge/MCP-24_tools-7C3AED)](docs/MCP.md)
&nbsp;
[![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white)](https://go.dev/)
&nbsp;
[![SvelteKit](https://img.shields.io/badge/SvelteKit-Svelte_5-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev/)
&nbsp;
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker&logoColor=white)](https://www.docker.com/)

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

[**Live Demo** — Documentation Graph](https://thask.kimgh06.com/shared/562a734b85200bbdd65a65e18e066dc377b7dcfd3c86edb1eab4e6aece9a9bbf) · [**Architecture Graph**](https://thask.kimgh06.com/shared/de5cb3d3587d2479d6c875f873bd6479f031187e4054fd8cc93eafca8c840691)

</div>

---

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

<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](docs/CLI.md) · [MCP Guide](docs/MCP.md)

### 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](docs/DATABASE.md#provenance--audit-migrations-006010)

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

### 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](docs/PLUGINS.md).

### 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](backend/api/README.md)

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

```
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/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`):
   ```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](docs/MCP.md) for details and the
[official Claude Code plugin](docs/CLAUDE_CODE_PLUGIN.md) 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](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
``