Dex - Persistent Task Tracking for AI Agents

Dex is a task tracking system that acts as a master coordinator for complex work—breaking down tasks, tracking progress, and preserving context across sessions. Unlike ephemeral session tracking, dex tasks are stored as files in the repository.

Installation

npm install -g @zeeg/dex
# or
pnpm add -g @zeeg/dex
# or
bun add -g @zeeg/dex

Core Concepts

• Persistence: Tasks survive beyond the current session as .dex/ files in the repo
• Repository-local storage: Before planning inside a project, run dex dir. If it points at global storage such as ~/.config/dex/local, the current directory is not being treated as a repo-local Dex workspace. Initialize or enter the project repo, ensure .dex/ exists if needed, then re-run dex dir before creating backlog items.
• Context Preservation: Decisions, progress, and rationale are captured
• Hierarchy: 3-level structure (Epic → Task → Subtask)
• Configuration: Tasks can block other tasks
• GitHub/Shortcut Sync: Optional sync to Issues/Stories for permanent records

Related reference: references/content-audit-and-devtools-gates.md covers content-completeness audit scripts plus Chrome DevTools MCP verification gates for content-model epics.

Core Commands

Dashboard & Listing

dex                    # Show dashboard (default command)
dex status             # Same as above - shows stats, ready tasks, blocked, completed
dex status --json      # Output as JSON

dex list               # List pending tasks in tree view
dex list --all         # Include completed tasks
dex list --ready       # Only unblocked tasks
dex list --blocked     # Only blocked tasks
dex list --in-progress # Only in-progress tasks
dex list --query "auth" # Search in name/description
dex list --flat        # Plain list instead of tree

Creating Tasks

dex create "Task title"

dex create "Task title" --description "Full implementation details..."
dex create "Task title" --description "..." --priority 2
dex create "Task title" --blocked-by <other_task_id>
dex create "Subtask title" --parent <parent_task_id>

Viewing & Editing

dex show <task_id>              # View full task details
dex show abc123 --expand        # Show ancestor descriptions
dex show abc123 --full          # No truncation
dex show abc123 --json          # JSON output

dex edit <task_id> --name "New name"
dex edit <task_id> --description "Updated context"
dex edit <task_id> --add-blocker <other_id>
dex edit <task_id> --remove-blocker <other_id>

Status Management

dex start <task_id>             # Mark as in progress
dex start <task_id> --force     # Re-claim already in-progress task
dex complete <task_id> --result "What was accomplished"
dex complete <task_id> --result "..." --commit <sha>
dex complete <task_id> --result "..." --no-commit
dex delete <task_id>            # Delete task (and children)
dex archive <task_id>           # Archive completed task

Planning

dex plan path/to/plan.md        # Create tasks from markdown plan
dex plan docs/SPEC.md --priority 2
dex plan feature.md --parent <id>

GitHub Integration

dex sync                        # Sync all tasks to GitHub Issues
dex sync <task_id>              # Sync specific task
dex sync --dry-run              # Preview sync
dex sync --github               # GitHub only
dex sync --shortcut             # Shortcut only

dex import #42                  # Import GitHub issue
dex import --all                # Import all dex-labeled issues
dex import sc#123               # Import Shortcut story

dex export <task_id>            # Export to GitHub without sync

When to Use Dex

Use dex when:

• Work spans multiple sessions or days
• Complex features need breakdown into steps
• Context and decisions must be preserved
• Work might be handed off or revisited
• Building a backlog before execution

Skip dex when:

• Quick, single-session task
• No context needs preserving
• Overhead isn't worth it

Workflow for Agents

Repository-local storage check

Before creating a project backlog, verify Dex is using repository-local storage:

dex dir

Expected for a project backlog: <repo>/.dex. If it resolves to a global path (for example ~/.config/dex/local), make the project a git repo first:

git init
mkdir -p .dex
dex dir

Dex may have a global config already, so dex init -y can fail with "Config file already exists"; that is not the fix. The durable fix is ensuring the project is a git repo so Dex scopes storage locally. Keep .dex/ project-local for epics/task lists that belong to the repo.

Starting New Work

1. Verify storage scope before creating anything:

dex dir

If it prints a global path (for example ~/.config/dex/local) while you are planning project work, stop and fix the workspace first: enter the correct repo or initialize git for the project, create .dex/ if needed, then re-run dex dir until it points inside the project. Do not create project epics in global Dex by accident.

1. Create task with full context:

dex create "Add JWT authentication" --description "
## Goal
Implement JWT-based auth for the API.

## Requirements
- Token generation on login
- Verification middleware for protected routes
- Refresh token flow

## Files
- src/middleware/auth.ts
- src/routes/auth.ts

## Acceptance Criteria
- POST /api/auth/login returns JWT
- Protected routes return 401 without valid token
- All 24 tests passing
"

1. For complex work, break into subtasks:

dex create "Create auth middleware" --parent <parent_id>
dex create "Add login endpoint" --parent <parent_id>
dex create "Add token refresh flow" --parent <parent_id>

1. Mark as in progress:

dex start <task_id>

During Implementation

dex list                        # Check current tasks
dex show <task_id>              # Review context
dex edit <task_id> --description "Updated: also need refresh tokens"

Completing Tasks

dex complete <task_id> --result "
Added POST /api/auth/login endpoint.
Verifies credentials with bcrypt, returns JWT access token (15m)
and refresh token (7d). All 24 tests passing.
" --commit <sha>

Writing Good Task Context

Include:

• What needs to be done (specific, not vague)
• Why it's needed (background, motivation)
• How to approach it (files to modify, patterns to follow)
• Done when (acceptance criteria)
• Verification gates for risky/big-bang work: content audits, build/check commands, and browser verification steps. If Chrome DevTools MCP is available, name the exact flows it must verify rather than leaving “browser tested” vague.

Good:

"Add rate limiting to /api/auth endpoints. Use express-rate-limit, 5 requests per minute per IP for /login, 20/min for /refresh. Return 429 with Retry-After header. Add to src/middleware/rate-limit.ts, apply in src/routes/auth.ts."

Bad:

"Add rate limiting"

Writing Good Results

Include:

• What changed (implementation summary)
• Key decisions (and why)
• Verification (tests passing, manual testing done)

For browser-app implementation tasks, especially Scott's SvelteKit projects, record concrete Chrome DevTools MCP evidence in the Dex completion result. Do not write generic "browser tested". Name the route/page, the clicked flow, observed state changes, console result, and screenshot path if layout/highlighting was visually checked. See references/devtools-mcp-verification.md.

Good:

"Added rate limiting with express-rate-limit. Login: 5/min, refresh: 20/min. Returns 429 with Retry-After header. Added 6 tests for rate limit scenarios. All 30 tests passing."

Good browser-task result:

"npm run check passed; npm run build passed; Chrome DevTools MCP verified /op-xy loads, selecting Move 5 updates Touch Now, completing all Moves reaches 100%, console has no runtime errors, screenshot saved at /tmp/flow.png."

Bad:

"Added rate limiting"

Task Hierarchy

• Epic: Large initiatives (5+ tasks). Example: "Add user authentication system"
• Task: Significant work items. Example: "Implement JWT middleware"
• Subtask: Atomic steps. Example: "Add token verification function"

Maximum depth is 3 levels.

Behavior Notes

• Subtasks must complete before parent can be completed
• Blocked tasks CAN be completed (warning shown) for flexibility
• Deleting a parent deletes all children
• Use GitHub issue numbers (permanent) in commits, not task IDs (ephemeral)

Configuration

dex init                        # Interactive setup for global config (~/.config/dex/dex.toml)
dex init -y                     # Accept defaults; fails harmlessly if global config already exists
dex dir                         # Print task storage path; ALWAYS verify this before creating project tasks
dex dir --global                # Print global config path
dex config --list               # Show all config values
dex config sync.github.enabled=true  # Enable GitHub sync
dex doctor                      # Check for issues
dex doctor --fix                # Check and fix issues

Repo-local storage guardrail

For project planning, prefer repo-local Dex storage so tasks live with the project instead of the global store.

Before creating an epic/task list:

# from the project root
git rev-parse --is-inside-work-tree || git init
mkdir -p .dex
dex dir

Proceed only after dex dir prints <project>/.dex. If it prints something under ~/.config/dex/local, the current directory is not being treated as the project store yet — initialize/enter the git repo and re-check. This matters for Scott: project Dex planning should be local, not global.

Session Handoff

When ending a session with incomplete work:

dex edit <task_id> --description "
## Progress
- Completed: JWT middleware added
- In Progress: Login endpoint (70% done)
- Blocked: Need refresh token strategy

## Next Steps
- Finish login endpoint validation
- Add refresh token rotation
"

Keep task in_progress so next session knows to continue.