pokedo

PokeDo

A Pokemon-themed CLI task manager and wellbeing tracker. Complete tasks to catch Pokemon, build your collection, and track your mental and physical wellbeing.

Version: 0.4.0 License: MIT Python: 3.10+

CI Version

Table of Contents

Features

Task Management

Pokemon System

Wellbeing Tracking

Progression

Multiplayer (PvP)

Terminal User Interface (TUI)

Installation

Requirements

Install from Source

# Clone the repository
git clone https://github.com/tldrwtf/pokedo.git
cd pokedo

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install PokeDo
pip install -e .

Quick Start

# 1. Initialize (downloads Pokemon data)
pokedo init --name "YourName" --quick  # Quick start with Gen 1 only

# 2. Add your first task
pokedo task add "Complete a task" --difficulty easy

# 3. Complete the task and catch a Pokemon!
pokedo task complete 1

# 4. View your dashboard
pokedo

Usage

You can use pd as a shorthand for pokedo once installed.

Initialize

# Full initialization (all 1025 Pokemon, takes a few minutes first time)
pokedo init --name "Ash"

# Speed up full initialization with parallel requests
pokedo init --name "Ash" --concurrency 20

# Quick start with Gen 1 only (151 Pokemon)
pokedo init --name "Ash" --quick

# Initialize specific generation
pokedo init --name "Ash" --gen 9  # Paldea only

Tasks

# Add a task
pokedo task add "Complete project report" --category work --difficulty hard --due tomorrow

# List tasks
pokedo task list
pokedo task list --today
pokedo task list --category work

# Complete a task (triggers Pokemon encounter!)
pokedo task complete 1

# Edit/delete tasks
pokedo task edit 1 --priority urgent
pokedo task delete 1

Pokemon

# View your team
pokedo team
pokedo pokemon team

# View all Pokemon
pokedo pokemon box

# View Pokedex
pokedo pokedex
pokedo pokemon pokedex --caught
pokedo pokemon pokedex --gen 3  # Filter by generation

# Preview a Pokemon sprite in the terminal
pokedo sprite pikachu
pokedo pokemon sprite 25
pokedo pokemon sprite charizard --shiny
pokedo sprite eevee --bg '#1e1e2e'  # Custom background color

# Manage team
pokedo pokemon set-active 5
pokedo pokemon remove-active 5

# Evolve Pokemon
pokedo pokemon evolve 3

# Nickname
pokedo pokemon nickname 1 "Sparky"

# Release
pokedo pokemon release 10

Wellbeing

# Quick commands
pokedo mood 4 --note "Feeling productive"
pokedo exercise cardio --duration 30 --intensity 4
pokedo sleep 7.5 --quality 4
pokedo water --glasses 8
pokedo meditate 15

# Full commands
pokedo wellbeing mood 5
pokedo wellbeing exercise running --duration 45
pokedo wellbeing today

Stats & Profile

# Dashboard
pokedo
pokedo daily

# Profiles
pokedo init --name "Misty"
pokedo profile set-default Misty

# Profile
pokedo profile
pokedo stats profile
pokedo profile set-default <name-or-id>

# Streaks
pokedo streaks

# Badges
pokedo badges

# Inventory
pokedo stats inventory

# History
pokedo stats history --days 14

TUI (Terminal User Interface)

Launch the interactive terminal UI for a full-featured graphical experience.

pokedo tui

Dashboard Keybindings:

Key Action
q Quit the TUI
r Refresh dashboard
p Switch profiles
t Open task management

Task Management Screen (press t from dashboard):

The task screen provides full CRUD operations with tabbed filtering:

Key Action
a Add new task
c Complete selected task (triggers Pokemon encounter)
e Edit selected task
d Delete selected task (with confirmation)
r Refresh task lists
Escape Return to dashboard

Completing a task in the TUI triggers the full encounter flow with XP rewards, streak updates, and Pokemon catching, just like the CLI.

Multiplayer (PvP Battles)

Requires a running PokeDo server. See Server Usage below.

# Register an account
pokedo battle register -u myname -p mypass

# Challenge another trainer
pokedo battle challenge opponent_name -u myname -p mypass

# Accept a challenge (as the opponent)
pokedo battle accept <battle-id> -u opponent -p theirpass

# Submit your team
pokedo battle team <battle-id> -u myname -p mypass

# Attack with a move (index 0-3)
pokedo battle move <battle-id> -m 0 -u myname -p mypass

# Switch to a different Pokemon (team slot index)
pokedo battle switch <battle-id> 1 -u myname -p mypass

# Forfeit
pokedo battle forfeit <battle-id> -u myname -p mypass

# Check battle status
pokedo battle status <battle-id> -u myname -p mypass

# View battle history
pokedo battle history -u myname -p mypass

Leaderboard

# Global leaderboard (sorted by ELO by default)
pokedo leaderboard show

# Sort by wins
pokedo leaderboard show --sort battle_wins

# Your own profile
pokedo leaderboard me -u myname

Server Usage (Optional)

PokeDo includes a FastAPI server for multiplayer battles, leaderboard tracking, and cloud synchronization. The server uses PostgreSQL for persistent state and the lifespan context manager pattern.

  1. Start with Docker Compose (recommended):

    docker-compose up -d

    This starts both PostgreSQL and the PokeDo server.

  2. Or run manually:

    # Start PostgreSQL separately, then:
uvicorn pokedo.server:app --reload --port 8000

    (Ensure you have installed development dependencies: pip install -e ".[dev]")

  3. Environment variables:

    Variable Default Description
    POKEDO_DATABASE_URL postgresql://pokedo:pokedopass@localhost:5432/pokedo Postgres connection
    POKEDO_SECRET_KEY your-secret-key-keep-it-secret JWT signing secret
    POKEDO_SERVER_URL http://localhost:8000 Server URL for CLI

  4. Register and battle:

    pokedo battle register -u myname -p mypassword
pokedo battle challenge opponent -u myname -p mypassword

    See MULTIPLAYER.md for the full battle flow.

How It Works

Catching Pokemon

When you complete a task, there’s a chance to encounter a Pokemon:

Rarity Tiers

Generation Support

Shiny Pokemon

Streak Rewards

Wellbeing Bonuses

Type Affinities

Task categories influence Pokemon type encounter probabilities:

Category Boosted Types
Work Steel, Electric, Normal
Exercise Fighting, Fire, Rock
Learning Psychic, Ghost, Dark
Personal Normal, Fairy, Flying
Health Grass, Water, Poison
Creative Fairy, Dragon, Ice

Wellbeing actions also affect type encounters:

Recent Fixes & Behavior Notes

EV/IV System

This system provides RPG mechanics for training your Pokemon’s stats:

Task Categories influence which stats are trained:

Task Category Stat Trained
Work Special Attack
Exercise Attack
Learning Special Defense
Health HP
Personal Defense
Creative Speed

Task Difficulty determines the EV yield:

Difficulty EV Yield
Easy 1 EV
Medium 2 EVs
Hard 4 EVs
Epic 8 EVs

Data Storage

All data is stored locally in ~/.pokedo/:

Development

The project includes a FastAPI server (pokedo/server.py) for multiplayer battles, a global leaderboard, and cloud synchronization. The server uses PostgreSQL via SQLModel and JWT-based authentication.

# Install with dev dependencies
pip install -e ".[dev]"

# Run all tests (556 tests)
pytest

# Run tests with coverage
pytest --cov=pokedo

# Run specific test file
pytest tests/test_battle.py

# Run multiplayer tests only
pytest tests/test_moves.py tests/test_battle.py tests/test_server.py -v

For more development information, see:

Troubleshooting

Common Issues

“Command not found: pokedo”

“Database error” on first run

TypeError: cannot use 'pokedo.core.task.Task' as a dict key (unhashable type: 'Task') in TUI

Slow initialization

Pokemon sprites not displaying

API rate limiting

Reset Data

# Remove all PokeDo data (start fresh)
rm -rf ~/.pokedo

# Reinitialize
pokedo init --name "YourName"

FAQ

Q: Can I play offline? A: Yes, after initial setup. All Pokemon data is cached locally.

Q: How do I backup my progress? A: Copy the ~/.pokedo/ directory. The pokedo.db file contains all your data.

Q: What happens if I miss a day? A: Your daily streak resets to 0, but your best streak is preserved.

Q: Can I catch legendary Pokemon? A: Yes! Epic and hard tasks have small chances to encounter legendaries. Mythical Pokemon require special tickets earned from long streaks.

Q: How does shiny hunting work? A: Base shiny rate is 1%. Each day of your streak adds 0.5% (up to 10% max).

Q: Can I have multiple profiles? A: Yes. Each trainer profile is stored in the same local database. The CLI uses the default profile, and the TUI lets you switch profiles (press p) and set a new default.

Q: Does wellbeing tracking affect gameplay? A: Yes! Good sleep improves catch rates, hydration goals boost Water-type encounters, and meditation increases Psychic/Fairy encounters.

Q: How do I battle other players? A: Start the PokeDo server (see Multiplayer Guide), register an account, and use the pokedo battle commands. Battles are async and turn-based – you and your opponent submit actions independently, and the server resolves each turn.

Q: Do I need a server to play? A: No. All single-player features (tasks, Pokemon, wellbeing) work fully offline with a local SQLite database. The server is only needed for PvP battles and the leaderboard.

Q: What battle formats are available? A: Three formats: singles_1v1 (1 Pokemon), singles_3v3 (3 Pokemon, one active), and singles_6v6 (full team, one active). Doubles and tournaments are planned for the future.

Q: How does the ELO rating work? A: Starting rating is 1000 with K-factor 32. Winning against higher-rated opponents earns more points. Ranks range from Youngster (below 1100) to Pokemon Master (2100+).

Q: How do I evolve Pokemon? A: Level up your Pokemon by completing tasks. When evolution requirements are met, use pokedo pokemon evolve <id>.

Q: What is the difference between CLI and TUI? A: The CLI (Command Line Interface) uses typed commands like pokedo task add. The TUI (Terminal User Interface) launched with pokedo tui provides an interactive graphical experience with keyboard navigation, tabbed views, and real-time updates.

Project Structure

pokedo/
├── cli/           # Command-line interface (tasks, pokemon, battle, leaderboard)
├── core/          # Business logic, models, battle engine, move system
├── data/          # Database, API clients, server models
├── tui/           # Terminal user interface (Textual)
│   ├── app.py         # Main TUI application
│   ├── screens/       # Screen classes (tasks, etc.)
│   ├── widgets/       # Reusable UI components
│   └── styles/        # Textual CSS styling
├── server.py      # FastAPI server (auth, battles, leaderboard, sync)
└── utils/         # Configuration, helpers, sprite rendering

See ARCHITECTURE.md for detailed documentation.

Credits

License

MIT License - see LICENSE file for details.