taskwright

Persistent task DAG for developer workflows. Manage tasks with rich metadata, dependency graphs, file-based artifacts, and an event timeline — backed by SQLite, exposed via MCP server and CLI.

Install

npm install -g taskwright

Quick Start

# Create a project
tw project create "Auth Migration"

# Add tasks with dependencies
tw task add <project-id> "Design OAuth2 flow" -s L
tw task add <project-id> "Implement token service" --depends-on <task-1-id>
tw task add <project-id> "Write integration tests" --depends-on <task-2-id>

# Check what's ready to work on
tw dag ready <project-id>

# View the full tree
tw dag tree <project-id>

# Update status
tw task update <task-id> --status in_progress

# View timeline
tw timeline task <task-id>
tw timeline project <project-id>
tw timeline project <project-id> --kind task_status_changed

Architecture

Data Model

Four SQLite tables managed by Drizzle ORM:

• projects — top-level containers with status (active | paused | complete | archived)
• tasks — work items with hierarchy (epic | task | subtask), size (S | M | L | XL), status state machine, dependency graph, and rich metadata (background, problem, requirements, solution, decisions)
• artifacts — files and links attached to tasks (document | code | link | media | other)
• events — append-only timeline recording all state changes

Task Status State Machine

backlog → pending → ready → in_progress → done
                                  │
                                  ▼
                                failed → pending (retry)

Any state → cancelled

Dependency Graph

Tasks declare dependencies via depends_on. The DAG engine provides:

• Ready detection — tasks whose dependencies are all done
• Blocked detection — tasks with unmet dependencies
• Cycle detection — prevents circular dependency chains
• Topological sort — valid execution ordering

CLI Reference

Projects

tw project create <name> [-d <description>]   # Create a project
tw project list [-s <status>]                  # List projects
tw project status <project-id>                 # Task count breakdown

Tasks

tw task add <project-id> <title> [-k epic|task|subtask] [-s S|M|L|XL] [-p <priority>] [--depends-on <ids...>]
tw task list <project-id> [-s <status>]        # List/filter tasks
tw task show <task-id>                         # Task details
tw task update <task-id> [--status <status>] [--title <title>]

DAG

tw dag ready <project-id>                      # Tasks ready to start
tw dag blocked <project-id>                    # Blocked tasks + reasons
tw dag tree <project-id>                       # Hierarchical tree view

Timeline

tw timeline task <task-id> [-n <limit>]        # Task event history
tw timeline project <project-id> [-n <limit>] [-k <kind>]  # Project events

MCP Server (Claude Code)

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "taskwright": {
      "command": "npx",
      "args": ["taskwright-mcp"]
    }
  }
}

Available Tools

Agent Configuration

To let AI agents (Claude Code, Codex, Gemini CLI) manage tasks via MCP, add the following to your configuration files.

CLAUDE.md / AGENTS.md

Add this block to your project's CLAUDE.md or AGENTS.md:

## Task Management (taskwright)

This project uses **taskwright** for persistent task tracking via MCP.

### MCP Tools Available

Use these tools to manage work:

- `project_create` / `project_list` / `project_status` — manage projects
- `task_create` / `task_list` / `task_get` / `task_update` — manage tasks
- `dag_ready` / `dag_blocked` / `dag_tree` — query the dependency graph
- `artifact_add` / `artifact_list` — attach files/links to tasks
- `timeline_task` / `timeline_project` / `timeline_query` — view event history

### Workflow

1. **Before starting work:** call `dag_ready` to find tasks with all dependencies satisfied
2. **Starting a task:** call `task_update` with `status: "in_progress"`
3. **Recording decisions:** call `task_update` with the `solution` or `result` field
4. **Completing a task:** call `task_update` with `status: "done"` and a `result` summary
5. **If a task fails:** call `task_update` with `status: "failed"` and an `error` description
6. **Adding artifacts:** call `artifact_add` to attach specs, code, or reference links

### Task Status Flow

`backlog` → `pending` → `ready` → `in_progress` → `done`
Any status → `cancelled`. Failed tasks can retry: `failed` → `pending`.

### Conventions

- Always check `dag_ready` before picking up new work
- Set tasks to `in_progress` before starting implementation
- Record `result` or `error` when completing/failing a task
- Use `artifact_add` to link deliverables (docs, code, links) to tasks
- Check `dag_blocked` to understand what's holding up downstream work

Global Settings (~/.claude/settings.json)

Add the MCP server to your global or project settings:

{
  "mcpServers": {
    "taskwright": {
      "command": "npx",
      "args": ["taskwright-mcp"],
      "env": {
        "TASKWRIGHT_DB": ".taskwright/taskwright.db"
      }
    }
  }
}

Set TASKWRIGHT_DB to control where the database is stored. Defaults to .taskwright/taskwright.db in the current directory.

Development

git clone https://github.com/doyonghoon/taskwright.git
cd taskwright
npm install
npm run build
npm test

Tech Stack

• Runtime: Node.js 20+, TypeScript, ESM
• Database: SQLite via better-sqlite3 (synchronous), Drizzle ORM
• Validation: Zod schemas
• MCP: @modelcontextprotocol/sdk (stdio transport)
• CLI: Commander.js, Chalk
• Testing: Vitest (222 tests)

Project Structure

src/
├── db/           # Drizzle schema, client, test utils
├── core/         # Lifecycle state machine, DAG engine, artifacts, timeline
├── mcp/
│   ├── server.ts # MCP entry point (15 tools, stdio)
│   └── tools/    # Tool handlers (task, dag, project, artifact, timeline)
└── cli/          # Commander CLI (project, task, dag, timeline commands)