Getting Started with DopaDone

DopaDone is a desktop app that turns your task backlog into a slot machine — randomizing what comes up, rewarding progress with XP, and using every engagement trick in the book to keep you moving forward. It’s built for ADHD brains that struggle with boring-but-important tasks.

Installation

  1. Download the latest .dmg from GitHub Releases
  2. Open the DMG and drag DopaDone to your Applications folder
  3. Launch DopaDone — macOS may ask you to confirm since it’s from an identified developer

The app is code-signed and notarized. Auto-updates are built in — you’ll get new versions automatically.

First Launch

On first launch, DopaDone asks you to choose a vault directory. This is where all your data will be stored as markdown files. Pick any folder — an existing Obsidian vault works great, or create a new one.

DopaDone creates a dopadone/ subdirectory inside your chosen vault with files like tasks.md, projects.md, and habits/definitions.md. Everything is plain text you can read and edit.

Your First Run

  1. Start a Run — hit the Start Run button. A tumbling animation plays as the system picks your first task.
  2. Face one task — you’ll see a single task with a 5-minute timer. No list of 47 things generating guilt. Just this one thing.
  3. Take any action — the big glowing Progress button is the point. You don’t have to finish anything. Move it forward, jot a note, then let the machine pick the next one.
  4. Earn XP — every action earns experience points. Priority, urgency, focus time, and flow bonuses stack up. Level up and the screen erupts.
  5. Keep going or stop — when the timer expires, click “Still Working?” to continue with a growing focus multiplier, or let the next task appear.

After 2 hours of inactivity, the run ends and you see a summary: top tasks, XP earned, and focus time.

Done for Now

Sometimes a task isn’t right for this moment. Open the action menu on any task and choose Done for now to hide it temporarily — for an hour, until tomorrow, or until next week. The task leaves the pool immediately.

DopaDone monitors snoozed tasks in the background. If something changes in the source — a new comment on a GitHub issue, an update in Todoist — the task wakes up early so you don’t miss it. You can also go to Settings > Snoozed Tasks to see everything that’s hidden and manually wake tasks up.

Task Sources

DopaDone pulls tasks from multiple sources — all mixed into one weighted pool. Go to Settings to manage them.

Internal Tasks

Create projects and tasks directly in DopaDone. Tasks have priority (P1–P4), optional start dates and deadlines, and can be assigned to projects.

Todoist

Paste your API token (find it in Todoist Settings > Integrations > Developer). DopaDone pulls your Todoist tasks into the pool. Projects, labels, priorities, due dates, and sequential project ordering all carry over.

GitHub Issues

Connect any GitHub repository to pull open issues as tasks. Issues inherit their labels and priority from GitHub labels.

Markdown Vault

Scan an Obsidian-compatible vault directory for tasks — checklist items in markdown files with frontmatter. Hashtags in the file become labels on the task.

You can add multiple instances of Todoist and GitHub connectors to pull from different accounts or repositories.

Setting Up Habits

Go to Settings > Habits to define recurring habits — medication, meals, exercise, whatever you tend to forget when hyperfocusing. Each habit has:

  • A recurrence rule (daily, weekdays, custom)
  • A time window — when it should start appearing
  • A linger duration — how long it stays in the pool if you miss it
  • Priority — P1 habits appear more frequently in the pool than P4

Habits mix right into the task pool alongside your regular tasks. Tap any habit to see your stats — current streak, best streak, completion rate, and a 30-day heatmap showing which days you completed, declined, or missed.

Calendar Prep

Go to Settings > Calendars to connect ICS calendar feeds. DopaDone creates prep tasks before your events:

  1. Add a calendar feed URL
  2. Define rules that match event names (e.g., “standup”, “1:1”)
  3. Each rule has prep steps with configurable lead times — “Anything to prepare?” at 48 hours, “Review notes” at 2 hours

As events approach, their prep tasks escalate in urgency.

Presets

Presets are named weight sets that shape which tasks are more likely to appear. Go to Settings > Presets to create and configure them.

  • Work preset — boost work-related criteria during business hours, suppress personal tasks
  • Evening preset — flip the weights for relaxation and personal errands
  • Errands preset — activate when you’re outside a geographic radius of home

Each preset has a criteria_weights map — keys are criteria strings (labels, auto-injected criteria like priority:p1, due:overdue, assignee:me) and values are weight multipliers. A default_weight applies to tasks that don’t match any criteria.

Presets can be activated in three ways: always on, always off, or triggers (schedule blocks and/or location rules). Multiple active presets stack their weights together.

System presets are built-in weight configurations (like “Defaults” which provides baseline priority/urgency/deadline weighting). You can toggle them on/off but can’t edit their rules — duplicate one to customize it.

Labels

Labels are bare strings — there’s no registry, no IDs, no colors. They’re auto-discovered from usage across all sources:

  • Todoist tasks get their project name and ancestor project names as labels
  • Markdown tasks get their filename (without .md) as a label, plus any #hashtags
  • Habits and calendar rule steps store labels as plain strings
  • GitHub issues get their GitHub labels

You don’t create labels — they appear automatically as you use them across sources.

AI Coaching

DopaDone includes an optional AI coach that helps you break through resistance. Add your Anthropic API key in Settings > AI Coaching to enable it.

When a task appears, the coach suggests a concrete first action — not generic advice, but the literal next physical step. You respond with reactions (“I know my next step”, “Be more specific”, “I don’t want to do this”) and the coach adapts. It speaks your language and pushes past avoidance without empty cheerleading.

After a run ends, the run summary includes Coach’s Notes — a short reflection on your session patterns with one actionable insight for next time.

Your Data

Everything lives in markdown files in your vault:

  • dopadone/tasks.md — your internal tasks
  • dopadone/projects.md — project definitions
  • dopadone/presets.md — preset weights, schedules, location rules
  • dopadone/habits/ — habit definitions and active instances

The run summary shows a complete history of your run: every task action, source breakdown, priority analysis, and a full timeline. Use “Copy Run Data” to export it as markdown.

See the Vault Format reference for the complete file specification.