TimerForge User Guide

Everything you need to install, set up, and get the most out of TimerForge.

🪟 Windows 10+
🍎 macOS 10.15+
🐧 Ubuntu 20.04+ / Linux

📄 Want an offline copy of this guide? Save this page (Ctrl+S / Cmd+S) or print it to PDF.

🖨 Print / Save PDF

💾 Installation

Choose your operating system below for step-by-step installation instructions.

  1. Download the installer

    After purchase, check your email for the download link and download TimerForge-Windows.zip.

  2. Extract the ZIP

    Right-click the ZIP file → Extract All. Choose a folder like C:\Program Files\TimerForge or your Desktop.

  3. Run TimerForge.exe

    Double-click TimerForge.exe. If Windows SmartScreen appears, click More info → Run anyway. This is a false positive common with PyInstaller apps and is safe.

  4. Pin to taskbar (optional)

    Right-click the TimerForge icon in the taskbar while it's running → Pin to taskbar for quick access.

Antivirus warning? Some antivirus tools flag PyInstaller apps as suspicious — this is a known false positive. TimerForge contains no malware. You can add an exception in your antivirus settings or verify the file on VirusTotal.
  1. Download the archive

    After purchase, download TimerForge-macOS.zip from your email link.

  2. Extract and move to Applications

    Double-click the ZIP to extract. Drag TimerForge.app into your Applications folder.

  3. First launch — remove quarantine

    macOS may say the app is "damaged" because it isn't notarised yet. Open Terminal and run:

    xattr -cr /Applications/TimerForge.app

    Then double-click the app — it will open normally from now on.

Tip: You can also right-click TimerForge.app → Open → Open to bypass Gatekeeper without using Terminal.
  1. Download and extract

    After purchase, download TimerForge-Linux.tar.gz and extract it:

    tar -xzf TimerForge-Linux.tar.gz
  2. Make it executable
    chmod +x TimerForge
  3. Run the app
    ./TimerForge
  4. Move to a permanent location (optional)
    sudo mv TimerForge /usr/local/bin/TimerForge

    Then you can launch it from anywhere by typing TimerForge in a terminal.

No sound on Linux? Install PulseAudio utilities: sudo apt install pulseaudio-utils

🚀 First Launch

When TimerForge opens you'll see two windows:

🎛 Control Window

Where you configure timers — set the time, pick a theme, choose sounds, and manage multiple timers. Keep this open while you work.

⭕ Display Window

A floating circular timer that stays on top of other apps. Drag it anywhere on your screen. You can make it fullscreen or click-through (ghost mode).

Tip: Your layout, timers, and settings are automatically saved when you close the app and restored next time you open it.

▶️ Your First Timer

  1. Type a time or pick a preset

    In the text box, type a duration like 25m, 1h30m, or 90s. Or select a preset from the dropdown (Pomodoro, Break, Meeting, etc.).

  2. Press Enter or click Start

    The timer begins counting down. The circular display shows the remaining time and a coloured ring that shrinks as time passes.

  3. Pause, Resume, or Reset

    Use the Space key to pause/resume, or R to reset. You can also click the buttons in the Control Window.

  4. When the timer finishes

    A sound plays and "Finished!" appears (you can customise this message). Click Snooze to restart with a short break timer.

Supported time formats

25m  ·  1h  ·  1h30m  ·  90s  ·  2h15m30s

⏱ Multiple Timers

TimerForge can run as many timers simultaneously as you need. Each timer is independent — different times, different sounds, different colours.

  1. Add a timer

    Click Add Timer or press Ctrl+N. A new timer appears in the dropdown.

  2. Switch between timers

    Use the dropdown at the top of the Control Window to switch between timers. Each timer remembers its own time and settings.

  3. Open the multi-timer grid

    Press Esc to toggle the multi-timer display — a floating grid showing all your running timers at once. Each tile shows the time, name, and status. Drag individual tiles to reposition them.

  4. Remove a timer

    Select the timer from the dropdown and click Remove Timer or press Ctrl+D. You cannot remove the last timer.

Tip: All timers run independently — pausing Timer 1 does not pause Timer 2.

✏️ Renaming Timers

Give each timer a meaningful name so you know what it's for at a glance.

  1. Select the timer

    Choose the timer you want to rename from the dropdown in the Control Window.

  2. Click Rename

    Click the Rename button next to the dropdown. A dialog will appear.

  3. Enter the new name

    Type a name like "Pasta", "Deep Work", or "Cardio" and click OK. The name updates in the dropdown and in the display window.

🎨 Themes & Colours

Each timer can have its own colour theme. Switch to a timer and change the colour — it only affects that timer, not the others.

Dark (default)
Light
Dark – Red
Dark – Blue
Dark – Purple
Monochrome
High Contrast

Changing the font

Use the Font dropdown in the Control Window to change the typeface used in the timer display. 8 fonts are available including monospace, serif, and system fonts.

Opacity

Drag the Opacity slider (30%–100%) to make the display window more transparent — useful when overlaying the timer on top of other content.

🔊 Sounds

Built-in sounds

5 system sounds at different frequencies. Select one from the Sound dropdown. Click 🔊 Test to preview it before committing.

Custom MP3 / WAV

Click Custom Sound and pick any MP3, WAV, or M4A file from your computer. Great for specific alarm tones.

Interval notifications

Enable Notification sounds to get a subtle beep at 10s, 30s, 1m, and 5m remaining — so you know the timer is nearly done without watching it.

Background timer alerts

Enable Background timer alerts to hear a different sound when any non-active timer finishes — even if you're focused on another timer.

🖥 Display Window

The circular display window floats above all your other apps. Here's what you can do with it:

Move it

Click and drag the display window to any position on any monitor. Its position is saved automatically.

Fullscreen

Press F11 or click Full Screen to expand the timer to fill your entire screen — great for presentations.

Always on top

By default the display stays on top of other windows. Click Always On Top to toggle this if you need to hide it temporarily.

Ghost mode (click-through)

Press G to enable Ghost Mode. The timer becomes click-through — your mouse clicks pass straight through it to the app underneath. Press G again (from the Control Window) to disable.

Multi-timer display

Press Esc to open a separate floating grid showing all your timers. Each timer tile shows its name, countdown, and a colour-coded status indicator. Tiles are draggable — arrange them however you like.

💾 Session Saving

TimerForge automatically saves everything when you close the app and restores it next time you open it — no setup required.

What's saved:

All timers

Every timer you've created is restored — including its name, remaining time, and paused state.

Settings

Mode, theme, font, sound, opacity, snooze duration — all restored exactly as you left them.

Per-timer colours

Each timer's individual colour theme is saved and restored independently.

Window positions

The size and position of both the control and display windows are remembered.

Note: Timers that were running when you closed the app will be restored in a paused state — press Space or click Start to resume them.

Where is the data stored?

Windows: %APPDATA%\TimerForge\session.json
macOS: ~/Library/Application Support/TimerForge/session.json
Linux: ~/.config/timerforge/session.json

🔗 Sharing Timers

You can share any timer as a link that anyone can open in a browser — no app required.

  1. Set up your timer

    Configure the timer duration, theme, and name as you want the recipient to see it.

  2. Click Share

    Click the Share button in the Control Window. TimerForge uploads the timer config to timerforge.app.

  3. Copy the link

    A shareable link is copied to your clipboard automatically. Paste it in Slack, email, or anywhere else.

Note: Shared timers are available for 30 days. They can also be embedded in websites using the provided embed code.

⌨️ Keyboard Shortcuts

All shortcuts work when the Control Window is focused.

Start timer Enter
Pause / Resume Space
Reset timer R
Toggle multi-timer display Esc
Fullscreen display F11
Ghost mode (click-through) G
Add new timer Ctrl + N
Delete current timer Ctrl + D

💡 Use Case Examples

🍅 Pomodoro Technique

  1. Select 25m Pomodoro from the presets and press Enter.
  2. Work until the timer finishes.
  3. Click Snooze (or add a second timer set to 5 minutes) for your break.
  4. Repeat 4 times, then take a longer 15–30 minute break.

🍳 Cooking Multiple Dishes

  1. Add Timer 1 → rename to "Pasta" → set to 12m → Start.
  2. Press Ctrl+N → rename to "Sauce" → set to 8m → Start.
  3. Press Ctrl+N → rename to "Garlic Bread" → set to 5m → Start.
  4. Press Esc to open the multi-timer grid and watch all three at once.
  5. Each timer alerts you independently when it finishes.

🏋️ Exercise Intervals

  1. Add Timer 1 → rename to "Sprint" → Dark – Red theme → set to 30s.
  2. Add Timer 2 → rename to "Rest" → Dark – Blue theme → set to 1m.
  3. Enable Auto-restart so each timer loops automatically.
  4. Start both timers and use the coloured display to instantly see which phase you're in.

📽 Presentation / Meeting

  1. Set the timer to your presentation length (e.g. 20m).
  2. Press F11 to fullscreen the display on a second monitor.
  3. Enable Ghost mode (G) so the timer floats over your slides on the same screen without blocking clicks.

🔧 Troubleshooting

🪟 Windows: "Windows protected your PC"

Click More info → Run anyway. This SmartScreen warning appears because the app isn't code-signed yet. It is safe to run.

🍎 macOS: "App is damaged and can't be opened"

Open Terminal and run:

xattr -cr /Applications/TimerForge.app

Then launch the app normally. This only needs to be done once.

🐧 Linux: No sound

Install the required audio utilities:

sudo apt install pulseaudio-utils sound-theme-freedesktop

Then restart TimerForge.

⚙️ App won't start on Linux

Make sure the file is executable:

chmod +x TimerForge ./TimerForge

If you see Qt/display errors, try:

sudo apt install libxcb-xinerama0 libxcb-cursor0 libegl1

💾 How do I reset my saved session?

Delete the session file for your platform:

# Windows del %APPDATA%\TimerForge\session.json # macOS rm ~/Library/Application\ Support/TimerForge/session.json # Linux rm ~/.config/timerforge/session.json

The app will start fresh next time you open it.

📧 Still stuck?

Email us at [email protected] and we'll help you out.