source: flowtimer/README.md@ 7a52e57

# Flowtimer

Flowtimer is a customizable Pomodoro timer designed to enhance productivity by breaking work into intervals, typically 25 minutes long, separated by short breaks. It allows you to configure your work and break sessions through a JSON file and includes predefined phases of activity to help you stay focused.

## Features

- **Configurable Sessions:** Define your own work, short break, and long break durations through a JSON file.
- **Predefined Phases:** Start with standard Pomodoro phases or create your own.
- **Progress Tracking:** Visual feedback on time remaining for each phase.
- **Customizable Cycle:** Choose how many work sessions you want before taking a longer break.

## Getting Started

### Prerequisites

Ensure you have the following installed on your machine:

- Python 3.x

### Installation

1. Clone the repository:
   ```bash
   git clone --branch guix https://gitlab.kid.local:/legacy/flowtimer.git
   cd flowtimer
   ```

2. Install the required dependencies:
   ```bash
   pip3 install .
   ```

### Usage

1. **Create or Modify Configuration:**

   Flowtimer reads its configuration from a JSON file.
   
   Example `default.json`:
   ```json
   { "title": "Default",
  "blocks": [
      {"type": "Phase",
       "title": "MorningHuddle",
       "initial_ticks": 900
      },
      {"type": "Sequence",
       "title": "AM",
       "sequence": [
           {
               "title": "Tasking",
               "initial_ticks": 120
           },
           {
               "title": "Working",
               "initial_ticks": 5400
           },
           {
               "title": "Syncing",
               "initial_ticks": 300
           },
           {
               "title": "Break",
               "initial_ticks": 600
           }
       ],
       "initial_repetitions": 2
      },
      {"type": "Phase",
       "title": "Lunch",
       "initial_ticks": 2700
      },
      {"type": "Sequence",
       "title": "PM",
       "sequence": [
           {
               "title": "Tasking",
               "initial_ticks": 120
           },
           {
               "title": "Working",
               "initial_ticks": 5400
           },
           {
               "title": "Syncing",
               "initial_ticks": 600
           },
           {
               "title": "Break",
               "initial_ticks": 600
           }
       ],
       "initial_repetitions": 2
      }
  ]
}
   ```

   This configuration represents a standard Pomodoro cycle: three work sessions of 25 minutes each, separated by 5-minute short breaks, and followed by a 15-minute long break.

2. **Run Flowtimer:**
   ```bash
   python flowtimer.py --config /path/to/config_file.json
   ```

   This will start the timer based on the phases and durations specified in the JSON file.

3. **Adjusting Configuration:**
   To change the timings or the order of phases, simply edit the JSON file and rerun the script.

### Default Configuration

If no configuration file is provided, Flowtimer will use the following default settings:

- 25 minutes of work
- 5 minutes of short break
- 4 work sessions before a 15-minute long break

### Command-line Options

- `--config <file>`: Specify a custom JSON configuration file.
- `--start`: Start the Pomodoro timer with the current configuration.

### Example

```bash
python flowtimer.py --config myconfig.json
```

This command will start Flowtimer with a custom configuration provided in `myconfig.json`.

## Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss any changes or improvements.

## License

Flowtimer is open-source software licensed under the [MIT License](LICENSE).

## Acknowledgments

Special thanks to the Pomodoro Technique® for inspiring this tool.