dwork — Projects

dwork is an AI-native, Markdown-driven project manager built for teams that work with AI coding agents. Instead of locking your project data into a proprietary database, dwork uses plain Markdown files — specifically BACKLOG.md — as the single source of truth. A SQLite + FTS5 index runs alongside for fast search, and both a REST API and MCP server expose everything to your agents and tools.

How it works

dwork follows dtoolkit’s core design principles:

• Markdown is the source of truth. Every project lives in a directory with a BACKLOG.md file and a docs/ folder. You can read and edit these files with any text editor, and dwork keeps its SQLite index in sync.
• SQLite + FTS5 is just an index. The database is disposable — dwork sync rebuilds it from your Markdown files at any time.
• MCP + REST on the same port. The API server runs on port 7881, and the MCP server shares the same port. The web dashboard runs on 7882 (port + 1).
• Bearer token auth. All API access is authenticated via API keys managed through the CLI.

Getting started

1. Install dwork globally or as a project dependency:

   install

   pnpm add -g @dtoolkit/dwork

2. Initialize a new dwork workspace:

   terminal

   dwork init

   The interactive wizard creates ~/.dwork/ with a config.json and dwork.db, then scaffolds your first project.

3. Start the server and dashboard:

   terminal

   dwork start

   This launches the REST + MCP API on port 7881 and the dashboard on port 7882.

4. Check that everything is running:

   terminal

   dwork status

Tip

dwork works standalone, but it composes naturally with the rest of dtoolkit. Connect it to dbrain for persistent memory, or use dcontext to inject project context into your AI coding sessions automatically.

Projects

Each project gets its own directory under ~/.dwork/projects/ containing:

my-project/
├── BACKLOG.md      # Tasks — the source of truth
├── docs/           # Numbered Markdown documents
│   ├── 001-architecture.md
│   ├── 002-api-design.md
│   └── 003-deployment-notes.md
└── metadata.json   # Project config (name, description, created date)

Create a new project through the MCP create_project tool, the REST API, or the dashboard. dwork scaffolds the directory structure and creates an empty BACKLOG.md ready for tasks.

Project metadata

Each project tracks:

Field	Description
id	Auto-generated short ID
name	Human-readable project name
description	One-line summary
status	active, paused, or archived
created	ISO timestamp
updated	ISO timestamp (last modification)

Tasks

Tasks live inline in BACKLOG.md as Markdown list items with structured metadata in square brackets. This format is both human-readable and machine-parseable.

Task format

- [ ] Implement user authentication [feature|todo|P1|3h]
- [x] Fix login redirect loop [bug|done|P0|1h]
- [ ] Refactor database connection pool [chore|doing|P2|2h]
- [ ] Add rate limiting to API endpoints [task|todo|P1|4h]
- [ ] Remove deprecated v1 endpoints [chore|cancelled|P3|1h]

The metadata block follows the pattern [type|status|priority|estimate]:

Task types

Type	Use for
feature	New functionality or capabilities
task	General work items, research, or spikes
bug	Defects and regressions
chore	Maintenance, cleanup, dependency updates

Task statuses

Status	Description
todo	Not started
doing	Currently in progress
done	Completed
cancelled	Dropped or no longer needed

Task priorities

Priority	Meaning
P0	Critical — drop everything
P1	High — do this sprint
P2	Medium — next sprint
P3	Low — backlog

Estimates

Estimates use shorthand notation: 1h, 3h, 1d, 3d, 1w. These are optional but help with planning and the dashboard’s workload views.

Caution

Always edit BACKLOG.md as the source of truth. If you modify tasks through the API or MCP tools, dwork writes the changes back to the Markdown file. Avoid editing both simultaneously — the last write wins.

Docs

Each project supports numbered Markdown documents stored in the docs/ directory. These are intended for specs, architecture decisions, meeting notes, investigation logs, and anything else that supports the project but is not a task.

Documents are auto-numbered (001, 002, 003…) and indexed by FTS5 for full-text search. You can create, read, update, and list docs through the MCP tools, the REST API, or by directly adding Markdown files to the docs/ directory and running dwork sync.

terminal

# Sync Markdown files into the SQLite index
dwork sync

Search

dwork uses SQLite FTS5 (contentless) to provide full-text search across all tasks and documents in all projects. The search supports:

• Boolean operators (AND, OR, NOT)
• Phrase matching with quotes
• Prefix matching with *
• Column filtering

Search is exposed through the MCP search tool, the REST GET /search endpoint, and the dashboard’s search bar.

terminal

# Example: search via the REST API
curl -H "Authorization: Bearer $DWORK_KEY" \
  "http://localhost:7881/search?q=authentication+rate+limiting"

Dashboard

The dwork dashboard is a single-file React application served on port 7882 (one above the API port). It requires no build step — it loads React and dependencies from CDN and is served as a static asset by Fastify.

Features

View	Description
Overview	Global kanban board showing tasks across all projects, grouped by status
Project detail	Per-project view with tabs for kanban, task list, and docs
Task detail	Modal with full task info and a Markdown editor for notes
File tree	Docs browser with directory tree navigation
Search	Global full-text search with instant results

The dashboard supports light and dark themes and is fully responsive for mobile use.

Tip

The dashboard is read-write. You can create tasks, update statuses (drag-and-drop on the kanban), and edit docs directly in the browser. Changes are written back to the Markdown files.

Code graph

dwork integrates with @dtoolkit/codegraph-sdk to provide semantic code intelligence features. The code graph builds a knowledge graph from your codebase using tree-sitter WASM parsers, then exposes it through five dedicated MCP tools.

Graph tools

Tool	Description
graph_search	Search for symbols, functions, classes, or patterns across the codebase
graph_stats	Get statistics about the code graph — file count, symbol count, language breakdown
graph_trace	Trace the call chain for a specific function or method
graph_impact	Analyze the impact of changing a specific symbol — what depends on it
graph_context	Get the full context around a symbol — its definition, references, and related code

These tools allow AI agents to reason about code structure when working on tasks. For example, an agent can use graph_impact before refactoring a function to understand what will break, or graph_trace to follow a bug through the call chain.

MCP tools

dwork exposes 21 MCP tools (plus 5 graph tools) and 1 MCP resource. All tools delegate to the service layer and are available when the MCP server is running on port 7881.

Project tools

Tool	Description
create_project	Create a new project with scaffolded directory structure
get_project	Get project details by ID
list_projects	List all projects with optional status filter
update_project	Update project metadata (name, description, status)

Task tools

Tool	Description
add_task	Add a task to a project’s BACKLOG.md
get_tasks	List tasks for a project, with optional filters (status, type, priority)
update_task	Update task fields (status, priority, estimate, description)

Doc tools

Tool	Description
add_doc	Create a new numbered document in a project
get_doc	Read a specific document by number
get_docs	List all documents in a project
update_doc	Update the contents of a document

Search and navigation

Tool	Description
search	Full-text search across all tasks and docs
overview	Global statistics — project count, task breakdown by status, recent activity
what_to_do_next	AI-powered suggestion of the highest-impact next task

Sync and operations

Tool	Description
sync	Re-index all Markdown files into the SQLite FTS5 database

Graph tools

Tool	Description
graph_search	Search for symbols across the codebase
graph_stats	Code graph statistics and language breakdown
graph_trace	Trace call chains for a function
graph_impact	Impact analysis for a symbol change
graph_context	Full context for a symbol (definition, references, related)

MCP resource

Resource	Description
dwork://projects	Read-only resource listing all projects and their metadata

Tip

When using dwork with dcontext, MCP tools are automatically available in your AI coding sessions. The agent can create tasks, search docs, and check the project overview without leaving the conversation.

REST API

The REST API runs on port 7881 and mirrors the MCP tools. All endpoints require a Bearer token.

Endpoints

Method	Path	Description
GET	/health	Health check
GET	/overview	Global stats
POST	/projects	Create project
GET	/projects	List projects
GET	/projects/:id	Get project
PATCH	/projects/:id	Update project
POST	/projects/:id/tasks	Add task
GET	/projects/:id/tasks	List tasks
PATCH	/projects/:id/tasks/:taskId	Update task
POST	/projects/:id/docs	Add doc
GET	/projects/:id/docs	List docs
GET	/projects/:id/docs/:num	Get doc
PATCH	/projects/:id/docs/:num	Update doc
GET	/search	Full-text search
POST	/sync	Re-index Markdown files
GET	/keys	List API keys
POST	/keys	Create API key
DELETE	/keys/:id	Revoke API key

CLI commands

Command	Description
dwork init	Interactive setup wizard — creates ~/.dwork/, configures database, scaffolds first project
dwork start	Start the REST + MCP server (port 7881) and the dashboard (port 7882)
dwork status	Show server status, project count, and database stats
dwork sync	Re-index all Markdown files into the SQLite database
dwork configure	Update configuration interactively (ports, data directory, auth)
dwork keys	Manage API keys — list, create, revoke

Quick start

terminal

pnpm add -g @dtoolkit/dwork
dwork init
dwork start

With dbrain

terminal

pnpm add -g @dtoolkit/dwork @dtoolkit/dbrain @dtoolkit/dcontext
dbrain init
dwork init
dcontext install
dbrain start
dwork start

Configuration

dwork stores its configuration in ~/.dwork/config.json. You can edit it directly or use dwork configure for an interactive experience.

Setting	Default	Description
port	7881	REST + MCP API port
dataDir	~/.dwork	Data directory for database and projects
auth.enabled	true	Require Bearer token authentication
auth.keys	[]	API keys (managed via CLI or API)

Environment variables override config file values:

Variable	Overrides
DWORK_PORT	port
DWORK_DATA_DIR	dataDir

Architecture

┌─────────────────────────────────────────────────┐
│                   Dashboard                      │
│              React SPA (:7882)                   │
└──────────────────────┬──────────────────────────┘
                       │ HTTP
┌──────────────────────▼──────────────────────────┐
│              Fastify Server (:7881)              │
│         REST routes  +  MCP server              │
│                Bearer token auth                 │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│               Service Layer                      │
│  projects / tasks / docs / search / sync         │
└────────┬─────────────────────────┬──────────────┘
         │                         │
┌────────▼────────┐    ┌──────────▼──────────┐
│   BACKLOG.md    │    │   SQLite + FTS5     │
│   docs/*.md     │    │   (index only)      │
│ (source of      │    │                     │
│  truth)         │◄───│   dwork sync        │
└─────────────────┘    └─────────────────────┘

Further reading

• dbrain — Memory — persistent memory for your agents
• dcontext — Hooks — inject project context into AI coding sessions
• dops — Observability — track agent performance and costs
• MCP Tools Reference — full schema reference for all MCP tools
• CLI Reference — complete CLI command reference