{"id":39031341,"url":"https://github.com/tldrwtf/pokedo","last_synced_at":"2026-02-18T23:03:23.039Z","repository":{"id":325409385,"uuid":"1101027044","full_name":"tldrwtf/pokedo","owner":"tldrwtf","description":"Pokemon themed task and wellbeing manager","archived":false,"fork":false,"pushed_at":"2026-02-17T21:38:56.000Z","size":237,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T01:32:58.987Z","etag":null,"topics":["cli-app","documentation","integrations","pokemon","python","task-manager","wellbeing"],"latest_commit_sha":null,"homepage":"https://tldrwtf.github.io/pokedo/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tldrwtf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP_ACTIONS.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"tldrwtf","custom":null}},"created_at":"2025-11-21T04:58:13.000Z","updated_at":"2026-02-17T21:37:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tldrwtf/pokedo","commit_stats":null,"previous_names":["tldrwtf/pokedo"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/tldrwtf/pokedo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldrwtf%2Fpokedo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldrwtf%2Fpokedo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldrwtf%2Fpokedo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldrwtf%2Fpokedo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tldrwtf","download_url":"https://codeload.github.com/tldrwtf/pokedo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tldrwtf%2Fpokedo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29597854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T22:25:43.180Z","status":"ssl_error","status_checked_at":"2026-02-18T22:25:42.766Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli-app","documentation","integrations","pokemon","python","task-manager","wellbeing"],"created_at":"2026-01-17T17:40:04.415Z","updated_at":"2026-02-18T23:03:18.029Z","avatar_url":"https://github.com/tldrwtf.png","language":"Python","funding_links":["https://github.com/sponsors/tldrwtf"],"categories":[],"sub_categories":[],"readme":"# PokeDo\n\nA Pokemon-themed CLI task manager and wellbeing tracker. Complete tasks to catch Pokemon, build your collection, and track your mental and physical wellbeing.\n\n**Version:** 0.3.1 | **License:** MIT | **Python:** 3.10+ \n\n![CI](https://github.com/tldrwtf/pokedo/actions/workflows/ci.yml/badge.svg?branch=main) ![Version](https://badgen.net/github/release/tldrwtf/pokedo/stable)\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n- [Server Usage (Optional)](#server-usage-optional)\n- [How It Works](#how-it-works)\n- [Data Storage](#data-storage)\n- [Development](#development)\n- [Troubleshooting](#troubleshooting)\n- [FAQ](#faq)\n- [Credits](#credits)\n\n## Features\n\n### Task Management\n\n- Create tasks with categories (work, exercise, learning, personal, health, creative)\n- Set difficulty levels (easy, medium, hard, epic) that affect XP and Pokemon rarity\n- Recurring tasks (daily, weekly, monthly)\n- Task priorities and due dates\n\n### Pokemon System\n\n- Catch Pokemon by completing tasks\n- **All 1025 Pokemon** from Gen 1 (Kanto) through Gen 9 (Paldea)\n- Pokemon rarity based on task difficulty\n- Pokemon **EVs (Effort Values) and IVs (Individual Values)** for stat training (partial implementation)\n- Shiny Pokemon (rare variants with boosted rates from streaks)\n- Legendary, Mythical, Pseudo-Legendary, and Ultra Beast encounters\n- Paradox Pokemon from Scarlet/Violet\n- Pokedex tracking with generation filtering\n- Active team of 6 Pokemon\n- Pokemon evolution based on level\n- Nickname your Pokemon\n\n### Wellbeing Tracking\n\n- Mood logging (1-5 scale)\n- Exercise tracking with type detection\n- Sleep logging with catch rate modifiers\n- Hydration tracking (Water-type bonuses)\n- Meditation logging (Psychic/Fairy bonuses)\n- Gratitude journaling (friendship bonuses)\n\n### Progression\n\n- Trainer levels and XP\n- **Trainer Classes** to specialize your journey (e.g., Ace Trainer, Hiker, Scientist). Choose your class via `pokedo stats set-class`.\n- Daily streaks with milestone rewards\n- Achievement badges\n- Inventory system (Pokeballs, evolution items)\n\n## Installation\n\n### Requirements\n\n- Python 3.10 or higher\n- pip (Python package manager)\n- Internet connection (for initial Pokemon data download)\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/tldrwtf/pokedo.git\ncd pokedo\n\n# Create virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install PokeDo\npip install -e .\n```\n\n## Quick Start\n\n```bash\n# 1. Initialize (downloads Pokemon data)\npokedo init --name \"YourName\" --quick  # Quick start with Gen 1 only\n\n# 2. Add your first task\npokedo task add \"Complete a task\" --difficulty easy\n\n# 3. Complete the task and catch a Pokemon!\npokedo task complete 1\n\n# 4. View your dashboard\npokedo\n```\n\n## Usage\n\nYou can use `pd` as a shorthand for `pokedo` once installed.\n\n### Initialize\n\n```bash\n# Full initialization (all 1025 Pokemon, takes a few minutes first time)\npokedo init --name \"Ash\"\n\n# Speed up full initialization with parallel requests\npokedo init --name \"Ash\" --concurrency 20\n\n# Quick start with Gen 1 only (151 Pokemon)\npokedo init --name \"Ash\" --quick\n\n# Initialize specific generation\npokedo init --name \"Ash\" --gen 9  # Paldea only\n```\n\n### Tasks\n\n```bash\n# Add a task\npokedo task add \"Complete project report\" --category work --difficulty hard --due tomorrow\n\n# List tasks\npokedo task list\npokedo task list --today\npokedo task list --category work\n\n# Complete a task (triggers Pokemon encounter!)\npokedo task complete 1\n\n# Edit/delete tasks\npokedo task edit 1 --priority urgent\npokedo task delete 1\n```\n\n### Pokemon\n\n```bash\n# View your team\npokedo team\npokedo pokemon team\n\n# View all Pokemon\npokedo pokemon box\n\n# View Pokedex\npokedo pokedex\npokedo pokemon pokedex --caught\npokedo pokemon pokedex --gen 3  # Filter by generation\n\n# Manage team\npokedo pokemon set-active 5\npokedo pokemon remove-active 5\n\n# Evolve Pokemon\npokedo pokemon evolve 3\n\n# Nickname\npokedo pokemon nickname 1 \"Sparky\"\n\n# Release\npokedo pokemon release 10\n```\n\n### Wellbeing\n\n```bash\n# Quick commands\npokedo mood 4 --note \"Feeling productive\"\npokedo exercise cardio --duration 30 --intensity 4\npokedo sleep 7.5 --quality 4\npokedo water --glasses 8\npokedo meditate 15\n\n# Full commands\npokedo wellbeing mood 5\npokedo wellbeing exercise running --duration 45\npokedo wellbeing today\n```\n\n### Stats \u0026 Profile\n\n```bash\n# Dashboard\npokedo\npokedo daily\n\n# Profiles\npokedo init --name \"Misty\"\npokedo profile set-default Misty\n\n# Profile\npokedo profile\npokedo stats profile\npokedo profile set-default \u003cname-or-id\u003e\n\n# Streaks\npokedo streaks\n\n# Badges\npokedo badges\n\n# Inventory\npokedo stats inventory\n\n# History\npokedo stats history --days 14\n```\n\n### TUI (Preview)\n\nLaunch the new terminal UI dashboard to get a live overview of your trainer profile, tasks, and team.\nPress `p` to switch profiles and optionally set a new default.\n\n```bash\npokedo tui\n```\n\n### Server Usage (Optional)\n\nPokeDo is developing a FastAPI server to enable cloud synchronization and multi-user features. This system uses `requests` for client-side pushing and `bcrypt` for secure authentication.\n\n1.  **Run the Server:**\n\n    ```bash\n    uvicorn pokedo.server:app --reload --port 8000\n    ```\n\n    (Ensure you have installed development dependencies: `pip install -e \".[dev]\"`)\n\n2.  **Register a User:**\n\n    ```bash\n    curl -X POST http://localhost:8000/register -H \"Content-Type: application/json\" -d \"{\\\"username\\\": \\\"testuser\\\", \\\"password\\\": \\\"testpassword\\\"}\"\n    ```\n\n3.  **Login and Get an Access Token:**\n\n    ```bash\n    curl -X POST http://localhost:8000/token -F \"username=testuser\" -F \"password=testpassword\"\n    ```\n\n    This will return a JSON object containing your `access_token`.\n\n4.  **Access Protected Endpoints (e.g., /users/me or /sync):**\n    Replace `\u003cYOUR_ACCESS_TOKEN\u003e` with the token received from the login step.\n    ```bash\n    curl -X GET http://localhost:8000/users/me -H \"Authorization: Bearer \u003cYOUR_ACCESS_TOKEN\u003e\"\n    ```\n\n## How It Works\n\n### Catching Pokemon\n\nWhen you complete a task, there's a chance to encounter a Pokemon:\n\n- **Encounter Rate**: ~70% base, increases with difficulty and streaks\n- **Rarity**: Determined by task difficulty\n  - Easy: Mostly common Pokemon\n  - Medium: Common + Uncommon\n  - Hard: Higher rare/epic chances\n  - Epic: Best legendary chances\n- **Catch Rate**: Based on Pokemon rarity and trainer level\n\n### Rarity Tiers\n\n- **Common** (60%): Early-route Pokemon from all generations\n- **Uncommon** (25%): Mid-evolution Pokemon, starters\n- **Rare** (10%): Final evolutions, Paradox Pokemon\n- **Epic** (4%): Final starter evolutions, Pseudo-Legendaries (Dragonite, Tyranitar, Salamence, Metagross, Garchomp, etc.), Ultra Beasts\n- **Legendary** (1%): Articuno, Zapdos, Moltres, Mewtwo, Lugia, Ho-Oh, Weather Trio, Creation Trio, Tao Trio, and more\n- **Mythical**: Mew, Celebi, Jirachi, Arceus, and more (special encounters only)\n\n### Generation Support\n\n- **Gen 1 (Kanto)**: #001-151\n- **Gen 2 (Johto)**: #152-251\n- **Gen 3 (Hoenn)**: #252-386\n- **Gen 4 (Sinnoh)**: #387-493\n- **Gen 5 (Unova)**: #494-649\n- **Gen 6 (Kalos)**: #650-721\n- **Gen 7 (Alola)**: #722-809\n- **Gen 8 (Galar)**: #810-905\n- **Gen 9 (Paldea)**: #906-1025\n\n### Shiny Pokemon\n\n- Base rate: 1/100\n- Streak bonus: +0.5% per day of streak\n- Perfect week: Boosted shiny chance\n\n### Streak Rewards\n\n- 3 days: Great Balls (better catch rate)\n- 7 days: Evolution Stone\n- 14 days: Ultra Balls\n- 30 days: Master Ball\n- 100 days: Legendary Ticket\n\n### Wellbeing Bonuses\n\n- **Good mood**: Pokemon happiness boost\n- **Exercise**: Type-specific encounter bonuses\n- **Good sleep**: Catch rate boost\n- **Hydration goal**: Water-type bonus\n- **Meditation**: Psychic/Fairy bonus\n- **Journaling**: Friendship evolution bonus\n\n### Type Affinities\n\nTask categories influence Pokemon type encounter probabilities:\n\n| Category | Boosted Types |\n|----------|---------------|\n| Work | Steel, Electric, Normal |\n| Exercise | Fighting, Fire, Rock |\n| Learning | Psychic, Ghost, Dark |\n| Personal | Normal, Fairy, Flying |\n| Health | Grass, Water, Poison |\n| Creative | Fairy, Dragon, Ice |\n\nWellbeing actions also affect type encounters:\n- **Hydration goal (8 glasses)**: Water-type bonus\n- **Meditation**: Psychic/Fairy bonus\n- **Exercise**: Fighting-type bonus\n\n---\n\n## Recent Fixes \u0026 Behavior Notes\n\n- **EV/IV persistence**: Pokemon now persist their EV/IV dictionaries, so every completion permanently boosts the lead Pokémon’s stats (see `pokedo/data/database.py` and `pokedo/core/pokemon.py`).\n- **Affinity-aware encounters**: The reward engine filters rarity pools by task/wellbeing affinities, backfills missing type data (`_ensure_pokedex_entry_types`), and consumes the best available ball (master/ultra/great) for each attempt (`pokedo/core/rewards.py`).\n- **Pokedex tracking parity**: Every catch or evolution increments `pokedex_seen`/`pokedex_caught` (with first-caught timestamps and shiny flags), keeping trainer completion metrics in sync (`pokedo/cli/commands/tasks.py`, `pokedo/cli/commands/pokemon.py`).\n- **Priority ordering \u0026 streak sync**: Task listings now sort using explicit numeric weights, and streak best counters update immediately on first-day or resumed streaks (`pokedo/data/database.py`, `pokedo/core/trainer.py`).\n\n### EV/IV System (In Progress)\n\nThis system introduces deeper RPG mechanics for training your Pokemon's stats:\n\n- **IVs (Individual Values):** Represents a Pokemon's innate potential (0-31 per stat), assigned randomly at capture.\n- **EVs (Effort Values):** Training points gained by completing tasks (max 510 total, 252 per stat).\n\n**Task Categories influence which stats are trained:**\n\n| Task Category | Stat Trained    |\n| ------------- | --------------- |\n| Work          | Special Attack  |\n| Exercise      | Attack          |\n| Learning      | Special Defense |\n| Health        | HP              |\n| Personal      | Defense         |\n| Creative      | Speed           |\n\n**Task Difficulty determines the EV yield:**\n\n| Difficulty | EV Yield |\n| ---------- | -------- |\n|------------|----------|\n| Easy       | 1 EV     |\n| Medium     | 2 EVs    |\n| Hard       | 4 EVs    |\n| Epic       | 8 EVs    |\n\n## Data Storage\n\nAll data is stored locally in `~/.pokedo/`:\n\n- `pokedo.db`: SQLite database\n- `cache/`: Cached PokeAPI data\n- `cache/sprites/`: Downloaded Pokemon sprites\n\n## Development\n\nThe project includes a FastAPI server (`pokedo/server.py`) for future cloud synchronization and currently provides **user authentication (registration/login with JWT)**.\n\n```bash\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=pokedo\n\n# Run specific test file\npytest tests/test_tasks.py\n```\n\nFor more development information, see:\n\n- [Architecture Documentation](docs/ARCHITECTURE.md) - System design and code structure\n- [Contributing Guide](docs/CONTRIBUTING.md) - How to contribute to PokeDo\n- [API Reference](docs/API.md) - Internal API documentation\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Command not found: pokedo\"**\n\n- Ensure you installed with `pip install -e .`\n- Check that your virtual environment is activated\n- Try running with `python -m pokedo` instead\n\n**\"Database error\" on first run**\n\n- Run `pokedo init --name \"YourName\"` to initialize the database\n- Check write permissions in your home directory\n\n**Slow initialization**\n\n- Full initialization downloads data for 1025 Pokemon\n- Use `--quick` flag for Gen 1 only (151 Pokemon)\n- Use `--gen N` to initialize a specific generation\n- Use `--concurrency N` to increase parallel PokeAPI requests\n\n**Pokemon sprites not displaying**\n\n- Sprites require terminal with image support (iTerm2, Kitty, etc.)\n- Text fallback is used in unsupported terminals\n- Check `~/.pokedo/cache/sprites/` for cached images\n\n**API rate limiting**\n\n- PokeAPI is free and has generous limits\n- Data is cached locally after first fetch\n- Clear cache: delete `~/.pokedo/cache/` folder\n\n### Reset Data\n\n```bash\n# Remove all PokeDo data (start fresh)\nrm -rf ~/.pokedo\n\n# Reinitialize\npokedo init --name \"YourName\"\n```\n\n---\n\n## FAQ\n\n**Q: Can I play offline?**\nA: Yes, after initial setup. All Pokemon data is cached locally.\n\n**Q: How do I backup my progress?**\nA: Copy the `~/.pokedo/` directory. The `pokedo.db` file contains all your data.\n\n**Q: What happens if I miss a day?**\nA: Your daily streak resets to 0, but your best streak is preserved.\n\n**Q: Can I catch legendary Pokemon?**\nA: Yes! Epic and hard tasks have small chances to encounter legendaries. Mythical Pokemon require special tickets earned from long streaks.\n\n**Q: How does shiny hunting work?**\nA: Base shiny rate is 1%. Each day of your streak adds 0.5% (up to 10% max).\n\n**Q: Can I have multiple profiles?**\nA: 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.\n\n**Q: Does wellbeing tracking affect gameplay?**\nA: Yes! Good sleep improves catch rates, hydration goals boost Water-type encounters, and meditation increases Psychic/Fairy encounters.\n\n**Q: How do I evolve Pokemon?**\nA: Level up your Pokemon by completing tasks. When evolution requirements are met, use `pokedo pokemon evolve \u003cid\u003e`.\n\n---\n\n## Project Structure\n\n```\npokedo/\n├── cli/           # Command-line interface\n├── core/          # Business logic and models\n├── data/          # Database and API clients\n└── utils/         # Configuration and helpers\n```\n\nSee [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed documentation.\n\n---\n\n## Credits\n\n- Pokemon data from [PokeAPI](https://pokeapi.co/)\n- Built with [Typer](https://typer.tiangolo.com/) and [Rich](https://rich.readthedocs.io/)\n- Inspired by the Pokemon franchise by Nintendo/Game Freak\n\n---\n\n## License\n\nMIT License - see LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftldrwtf%2Fpokedo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftldrwtf%2Fpokedo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftldrwtf%2Fpokedo/lists"}