Overview

flowstate-cli is a comprehensive, open-source command-line productivity suite designed for developers and creators who demand more from their tools. It combines deep work timers, robust task management, distraction blocking, and insightful productivity analytics—all in a privacy-first, scriptable CLI package.

Problem Statement

Modern knowledge work is plagued by distractions, context switching, and a lack of visibility into how we spend our time. Most productivity tools are either too simplistic, require cloud accounts, or don’t fit seamlessly into a developer’s workflow. There was a need for a tool that is powerful, extensible, and truly respects user privacy.

Solution

I built flowstate-cli to be:

  • Not just a timer, but a complete system for managing tasks, tracking focus, and blocking distractions.
  • Designed for those who live in the command line, with rich output and automation in mind.
  • Modular Python architecture, easy to contribute to and customize.
  • Works on Linux, macOS, and Windows.

Technical Implementation

Architecture & Tools

  • Language: Python 3.8+
  • Key Libraries:
    • typer for CLI
    • rich for beautiful terminal output
    • httpx for async API calls
    • plyer for notifications
    • python-daemon for background processes
  • Core Modules:
    • main.py: Typer CLI entrypoint with subcommands for auth, tasks, timers, stats, and more
    • api.py: Handles authentication and remote API integration (magic link login, token management)
    • config.py: Robust config system with local JSON storage and sensible defaults
    • timer.py & daemon.py: Pomodoro/focus timer logic, background daemon, notifications
    • flow_mode.py: Distraction blocking via hosts file manipulation (blocks social media, etc.)
    • task management: Add, list, start, complete, and remove tasks from the CLI

Example Usage

Task Management

flowstate add "Write project documentation"
flowstate list
flowstate start 1
flowstate done 1
flowstate rm 1

Pomodoro & Focus Timer

flowstate pom start
flowstate pom break short
flowstate pom stop
flowstate pom status

Distraction Blocking (Flow State Mode)

flowstate mode on   # Block distracting sites
flowstate mode off  # Unblock

Productivity Stats

flowstate stats

Configuration

flowstate config show
flowstate config set pomo_duration 30
flowstate config set notifications true

Project Setup

Dependencies

pip install flowstate-cli

Configuration

  • All settings are managed via a simple config file or CLI flags.
  • Session logs and task data are stored locally for privacy and review.

Impact

flowstate-cli is helping developers and creators:

  • Reduce distractions and context switching
  • Build sustainable deep work habits
  • Track and reflect on their productivity
  • Automate and script their focus routines

Conclusion

flowstate-cli is more than just a timer, it’s a complete productivity platform for the terminal. By combining simplicity, privacy, and extensibility, it empowers anyone to reclaim their most valuable resource: attention.

For more projects, check out my portfolio!