💠 FlowCoin

A terminal-based productivity game for Linux. Work sessions and tasks earn you coins, which you spend on themes in the shop. Pure Python standard library — no pip install required.

Requirements

• Linux (uses select() on stdin for live timers — POSIX only)
• Python 3.7+
• A terminal that supports 24-bit ANSI color (most modern terminals do)

Run it

python3 main.py

Your data (coins, sessions, tasks, purchases) lives in data/flowcoin.db (SQLite), created automatically on first run.

Features

• Flowtime timer — work until you naturally want to stop, press ENTER to end the session. You earn coins per minute worked, and get a suggested break length (worked time ÷ 5).
• Pomodoro timer — fixed work/break lengths (configurable in Settings), with a bonus for completing a full interval.
• Custom tasks — define non-timer tasks with their own fixed coin reward (e.g. "Answer emails" → 15 coins) and mark them complete whenever.
• Productivity charts — today's totals, a 7-day bar chart of minutes worked and coins earned, and all-time breakdown by session type. Rendered as plain ASCII bar charts, no dependencies needed.
• Theme shop — spend coins to unlock new color themes; ships with Ocean Breeze, Sunset, Matrix, and Synthwave, plus the free Default.
• Mini-games — a "Guess the Number" wager game ships as an example; built on a plugin system so more are easy to add.

Project layout

flowcoin/
├── main.py                 entry point / menu wiring
├── app/
│   ├── config.py            paths & default settings
│   ├── db.py                tiny SQLite wrapper
│   ├── ui.py                ANSI color + menu helpers (theme-aware)
│   ├── currency.py          coin balance get/add/spend
│   ├── theme_manager.py     loads themes/*.json, handles buy/equip
│   ├── task_manager.py      custom (non-timer) tasks
│   ├── stats.py             queries + ASCII bar charts
│   ├── timers/               <- pluggable timer modes
│   │   ├── base.py           BaseTimer interface, session logging
│   │   ├── flowtime.py
│   │   └── pomodoro.py
│   └── minigames/            <- pluggable mini-games
│       ├── base.py           BaseMinigame interface
│       └── guess_number.py
└── themes/                  <- drop a .json file here to add a theme
    ├── default.json
    ├── ocean.json
    ├── sunset.json
    ├── matrix.json
    └── synthwave.json

Extending it

Add a theme (no code!)

Drop a new file in themes/, e.g. themes/forest.json:

{
  "id": "forest",
  "name": "Forest",
  "price": 175,
  "colors": {
    "primary":   "#2e8b57",
    "secondary": "#6fae7f",
    "accent":    "#c9f0d5",
    "success":   "#33ff99",
    "warning":   "#ffcc33",
    "dim":       "#3f5f4a"
  }
}

The id must match the filename (minus .json) and be unique. It shows up in the shop on next launch — nothing else to wire up.

Add a new timer mode (e.g. "52/17")

1. Create app/timers/fifty_two_seventeen.py, subclass BaseTimer from app/timers/base.py, implement run(self, ui, theme) returning (duration_seconds, coins_earned, label).
2. Import it and add it to TIMER_REGISTRY in app/timers/__init__.py.

It'll automatically appear in the "Start a work session" menu.

Add a mini-game

1. Create app/minigames/your_game.py, subclass BaseMinigame from app/minigames/base.py, implement play(self, ui, theme). Use the currency module to pay out / take wagers.
2. Register it in GAME_REGISTRY in app/minigames/__init__.py.

It'll automatically appear in the "Mini-games" menu.

Settings

From the main menu → Settings, you can tune:

• Coins earned per minute worked
• Pomodoro work length (minutes)
• Pomodoro break length (minutes)
• Pomodoro completion bonus (coins)

Notes

• All timers use select() on stdin for a non-blocking live countdown — this is Linux/POSIX-specific and won't work as-is on Windows.
• The database schema is intentionally simple (one sessions table for every session type) so charts and future stats are easy to extend — just add a new session_type value.