Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tldrwtf/pokedo/llms.txt
Use this file to discover all available pages before exploring further.
The TUI is a full-screen interactive dashboard built with Textual. It gives you a live view of your trainer profile, active team, and pending tasks in a single window, with keyboard shortcuts for every action. Use the TUI when you want a heads-up display you can keep open while you work — it refreshes on demand and handles the full task lifecycle, including Pokemon encounters, without dropping you back to a shell prompt. Use the CLI (pokedo task add, pokedo task complete, etc.) when you want quick one-off commands or are scripting workflows.
Launching the TUI
If you have more than one trainer profile and no default is set, a profile-selector modal opens before the dashboard loads. Select a profile and optionally check Set as default profile so the modal does not appear next time.
Dashboard layout
The dashboard is divided into four panels arranged in two columns:
| Panel | Contents |
|---|
| Trainer | Name, level, XP progress (current/needed), trainer class, daily streak, total Pokemon caught |
| Team | Up to six active Pokemon with nickname, level, and a ✨ marker for shinies |
| Tasks | Up to eight pending tasks with ID, title, due date, and overdue status; a Today: X/Y count in the panel title |
| Help | Quick-reference list of dashboard keybindings |
Dashboard keybindings
| Key | Action |
|---|
t | Open task management screen |
r | Refresh all dashboard panels |
p | Open profile-switcher modal |
q | Quit the TUI |
Task management screen
Press t from the dashboard to open the task management screen. The screen provides full CRUD operations on your tasks, organized into four tabs:
| Tab | Shows |
|---|
| Active | Pending tasks that are not archived |
| Due Today | Tasks with a due date matching today |
| All | All non-archived tasks regardless of status |
| Archived | Archived tasks |
Task screen keybindings
| Key | Action |
|---|
a | Add a new task |
c | Complete the selected task (triggers Pokemon encounter) |
e | Edit the selected task |
d | Delete the selected task (confirmation required) |
r | Refresh all task tabs |
Escape | Return to the dashboard |
Use the Due Today tab at the start of your session to focus on what needs to get done today without scrolling through your full backlog.
Pokemon encounters in the TUI
Pressing c on a selected task runs the same reward pipeline as pokedo task complete <id> from the CLI:
- The task is marked complete and XP is awarded.
- Your lead Pokemon receives EVs in the stat tied to the task’s category.
- Your daily streak is updated.
- If the encounter roll succeeds (base ~70%, modified by difficulty and streak), a wild Pokemon appears with visual feedback in the TUI.
- The encounter resolves with a catch attempt using the best available Pokeball in your inventory.
All of this happens inline — you do not leave the task screen. After the encounter, the task disappears from the Active tab and the dashboard panels refresh automatically.
Profile switching
The TUI supports switching between trainer profiles without restarting.
Press p from the dashboard to open the profile-switcher modal. The modal lists all trainer profiles with their current level. Select a profile and click Continue. If you check Set as default profile, that trainer becomes the default for future sessions — equivalent to running:
pokedo profile set-default <name-or-id>
p does nothing.
To create a second profile without leaving your current session, open a separate terminal and run pokedo init --name "Misty". Then press p in the TUI to switch to it immediately.
Terminal requirements
The TUI runs in any terminal emulator that supports 256-color output and Unicode. No additional configuration is needed for the dashboard, keybindings, or task management.
Pokemon sprite previews inside the TUI require a terminal with inline image protocol support:
| Terminal | Sprite support |
|---|
| iTerm2 (macOS) | Full inline images |
| Kitty | Full inline images |
| WezTerm | Full inline images |
| Most others | Text-mode fallback |
~/.pokedo/cache/sprites/ after the first download, so they load instantly on subsequent renders.
In earlier versions of the TUI, a Textual widget stored a domain Task object in self._task. This conflicted with Textual’s internal Widget._task asyncio lifecycle field, causing a TypeError: cannot use 'pokedo.core.task.Task' as a dict key (unhashable type: 'Task') crash. The fix was to rename all domain-object fields to explicit names: _detail_task, _editing_task, and _completed_task. If you are writing custom Textual widgets or screens for PokeDo, never store app models in self._task — always choose an unambiguous name like _selected_task or _editing_task.