Taskdot

File-based issue tracker that lives inside your git repository. Manage issues, projects, milestones, ADRs, RFCs, PRDs, and more — all through Claude Code.

Inspired by Linear, but stored as Markdown files with YAML frontmatter in a .taskdot/ directory.

Features

• Issues with priorities, labels, assignees, relations (blocks/blockedBy), and comments
• Projects with milestones and progress tracking
• Teams and Users with role-based organization
• Labels for categorization
• ADRs (Architecture Decision Records) with RFC/PRD linking
• RFCs (Request for Comments) with review workflow
• PRDs (Product Requirements Documents) with issue linking
• Documents for external references
• HTML Viewer — interactive dashboard with kanban board, list view, filters, and dark/light theme
• Linear Import — full workspace import via Linear MCP tools

Installation

Prerequisites

• Claude Code CLI installed
• Node.js (for the viewer server)
• Git

Step 1: Clone the repository

git clone <repo-url> taskdot
cd taskdot

Step 2: Register the marketplace

Add the following entry to ~/.claude/plugins/known_marketplaces.json:

{
  "taskdot-marketplace": {
    "source": {
      "source": "directory",
      "path": "/absolute/path/to/taskdot"
    },
    "installLocation": "/absolute/path/to/taskdot",
    "lastUpdated": "2026-01-01T00:00:00.000Z"
  }
}

Replace /absolute/path/to/taskdot with the actual path where you cloned the repo.

Step 3: Install the plugin

Open Claude Code and run:

/plugin

Select taskdot from the list and install it. Then:

/reload-plugins

Usage

Initialize in a project

Navigate to any git repository and run:

/taskdot:init MyProject

This creates a .taskdot/ directory with:

.taskdot/
├── config.yml          # Project configuration and counters
├── viewer.html         # Static HTML viewer (committed to git)
├── issues/             # IS-0001.md, IS-0002.md, ...
├── comments/           # CM-0001.md, ...
├── projects/           # PJ-0001.md, ...
├── milestones/         # ML-0001.md, ...
├── documents/          # DC-0001.md, ...
├── teams/              # TM-0001.md, ...
├── users/              # US-0001.md, ...
├── labels/             # LB-0001.md, ...
├── adrs/               # ADR-0001.md, ...
├── rfcs/               # RFC-0001.md, ...
└── prds/               # PRD-0001.md, ...

Commands

Command	Description
/taskdot:init [name]	Initialize tracker in current repo
/taskdot:issue [title]	Create a new issue
/taskdot:issue IS-0001 status="Done"	Update an existing issue
/taskdot:list	List all open issues
/taskdot:list assignee=me	List issues assigned to you
/taskdot:status	Show project dashboard
/taskdot:view	Start viewer server and open browser
/taskdot:import	Import from Linear (requires Linear plugin)

Skills (auto-triggered)

These activate automatically based on what you ask:

• issues — Create, update, list, search, delete issues and comments
• projects — Manage projects, milestones, and documents
• workflow — Manage teams, users, labels, and statuses
• adrs — Create and manage Architecture Decision Records
• rfcs — Create and manage Requests for Comments
• prds — Create and manage Product Requirements Documents
• viewer — Generate and serve the HTML dashboard
• import — Import data from Linear via MCP tools

Viewer

The viewer is a self-contained HTML dashboard served by a local Node.js server:

/taskdot:view

This starts a server on http://localhost:24180 that reads .taskdot/ files directly. Features:

• Kanban board and list views
• Filter by status, priority, assignee, label
• Full-text search
• Issue detail panel with comments
• Dashboard with stats, progress, and recent activity
• Sidebar navigation (Issues, Projects, Teams, Users, ADRs, RFCs, PRDs)
• Dark/light theme toggle

Linear Import

To import your entire Linear workspace:

1. Install the Linear plugin via /plugin
2. Authenticate with /mcp (select Linear)
3. Initialize Taskdot: /taskdot:init
4. Import: /taskdot:import

The import uses Linear MCP tools to pull all users, teams, labels, projects, milestones, issues (with relations), comments, and documents.

Data Format

All entities are Markdown files with YAML frontmatter:

---
id: "IS-0001"
title: "Fix login timeout"
status: "In Progress"
priority: 2
assignee: "US-0001"
team: "TM-0001"
labels: ["LB-0001"]
createdAt: "2026-03-28T10:00:00Z"
updatedAt: "2026-03-28T14:30:00Z"
createdBy: "US-0001"
---

## Description

The login form times out after 5 seconds on slow connections.

Priority Levels

Value	Meaning
0	None
1	Urgent
2	High
3	Normal
4	Low

Entity ID Prefixes

Prefix	Entity
IS-	Issue
CM-	Comment
PJ-	Project
ML-	Milestone
DC-	Document
TM-	Team
US-	User
LB-	Label
ADR-	Architecture Decision Record
RFC-	Request for Comments
PRD-	Product Requirements Document

Cross-References

• Issue -> PRD: prdId field on issues
• ADR -> Issue: issueId field on ADRs
• ADR -> RFC/PRD: relatedRfcs and relatedPrds fields on ADRs
• Issue relations: blocks, blockedBy, relatedTo, duplicateOf

Plugin Structure

taskdot/
├── .claude-plugin/
│   └── marketplace.json     # Marketplace definition
├── plugin/
│   ├── .claude-plugin/
│   │   └── plugin.json      # Plugin manifest
│   ├── commands/             # Slash commands
│   ├── agents/               # Taskdot manager agent
│   ├── skills/               # Auto-triggered skills
│   │   ├── issues/
│   │   ├── projects/
│   │   ├── workflow/
│   │   ├── adrs/
│   │   ├── rfcs/
│   │   ├── prds/
│   │   ├── viewer/
│   │   └── import/
│   └── scripts/              # Server and utilities
├── docs/                     # Plans and specs
└── README.md

License

MIT