dex

Agent Coordination with dex

Version: 0.16+ (this doc assumes 0.16 features)

Command Invocation

Use dex directly for all commands. If not on PATH, use npx @zeeg/dex instead.

command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"

Core Principle: Tickets, Not Todos

Dex tasks are tickets - structured artifacts with comprehensive context:

• Name: One-line summary (issue title)
• Description: Full background, requirements, approach (issue body)
• Result: Implementation details, decisions, outcomes (PR description)

Think: "Would someone understand the what, why, and how from this task alone?"

Dex Tasks are Ephemeral

Never reference dex task IDs in external artifacts (commits, PRs, docs). Task IDs like abc123 become meaningless once tasks are completed. Describe the work itself, not the task that tracked it.

When to Use dex

Use dex when:

• Breaking down complexity into subtasks
• Work spans multiple sessions
• Context needs to persist for handoffs
• Recording decisions for future reference

Skip dex when:

• Work is a single atomic action
• Everything fits in one session with no follow-up
• Overhead exceeds value

dex vs Built-in Task Tools

Some AI agents (like Claude Code) have built-in task tools. These are session-only and not the same as dex.

	dex	Built-in Task Tools
Persistence	Files in .dex/	Session-only
Context	Rich (description + context + result)	Basic
Hierarchy	3-level (epic → task → subtask)	Flat

Use dex for persistent work. Use built-in task tools for ephemeral in-session tracking only.

Basic Workflow

Start Working on a Task

dex list                  # See pending tasks
dex start <id>            # Mark task as in progress
dex show <id>             # Full details
dex list --in-progress    # Show in-progress tasks