TwoMateOS Status Timer

Offline desktop app for tracking Work / Wait / Leave statuses with two timers for the current calendar day.

Русская версия → README_RU.md

Why use it

When you work with AI assistants like Cursor or Claude, it is easy to lose track of how your day is actually spent. TwoMateOS helps you measure:

• Work — time you actively do something yourself
• Wait — time spent waiting for the AI, a CI pipeline, builds, tests, or similar

That split makes your real efficiency visible. For example, Claude often thinks slower and longer than Cursor; even with parallel tasks, more time ends up in Wait, and effective throughput drops. Once you see the numbers, you can compare tools, workflows, and habits more honestly.

Requirements

• Python 3.10+
• Linux, Windows, or macOS
• System tray support for background mode (optional but recommended on Linux)

Installation

Clone the repository and install dependencies into a virtual environment:

git clone git@github.com:theSharque/TwoMateOs.git
cd TwoMateOs
python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt

On Linux, if the tray icon does not appear, install Qt platform extras (Ubuntu/Debian):

sudo apt install libxcb-cursor0

Optional: twomateos command in PATH

The twomateos script runs the app via the project venv. From the project directory:

mkdir -p ~/.local/bin
ln -sf "$(pwd)/twomateos" ~/.local/bin/twomateos

Make sure ~/.local/bin is on your PATH. After that you can start the app from anywhere:

twomateos

Alternative — add to ~/.bashrc:

alias twomateos='/path/to/TwoMateOs/twomateos'

How to run

From the project directory (after activation):

python app.py

Via launcher script (venv must exist):

./twomateos

Windows (cmd):

venv\Scripts\activate
python app.py

Windows (PowerShell):

venv\Scripts\Activate.ps1
python app.py

A small window opens with two timers and three colored buttons. The app keeps running in the system tray after you close the window (click X — it hides, not quits). To exit completely: tray icon → right click → Quit.

How to use

Status switching is automatic — you do not click the W / P / L buttons. The app watches its own window:

Your action	Status	What happens
TwoMateOS is visible, another app (IDE, browser) is in focus	Work	Green W timer runs
TwoMateOS window is in focus (you switched to it)	Wait	Yellow P timer runs
Window is hidden or minimized (app only in tray)	Leave	Both timers paused

Typical workflow with AI

1. Start TwoMateOS and leave the window open on screen or on a second monitor.
2. Work in Cursor / Claude / terminal — TwoMateOS stays in the background → Work (green) accumulates.
3. While the AI or CI is running and you are not coding, switch focus to the TwoMateOS window → Wait (yellow) accumulates.
4. Lunch or end of day — minimize or close the window → Leave (red), timers stop.

Timers show accumulated time for today from midnight (00:00:00). After restart, values are restored from the event log.

Colors and interface

Timers (top of the window)

Color	Label	Meaning
Green	W HH:MM:SS	Total Work time today — you were doing something in other apps
Yellow	P HH:MM:SS	Total Wait time today — TwoMateOS was in focus (waiting for AI, pipeline, etc.)

Buttons (bottom row)

Buttons mirror the current status. The active one has a dark border:

Button	Color	Status
W	Green	Work
P	Yellow	Wait
L	Red	Leave / break

Buttons are indicators only — status changes when you focus, hide, or minimize the window.

Daily statistics

Open Stats (button on the main window or Statistics in the tray menu). A calendar shows days with tracked activity. Select a date to see:

• W / P totals for that day
• A 720-pixel timeline (1 px = 2 minutes): green = Work, yellow = Wait, black = no data or Leave
• Hour labels 00–23 under the strip

For today, the timeline updates every second while the window is open.

System tray icon

The tray icon matches the current status:

Icon	Status
Green	Work
Yellow	Wait
Red	Leave

Hover shows a tooltip with status and both timers. Left click — show the window. Right click — Show / Quit.

Data storage

Events are stored in events.json:

OS	Path
Linux	~/.local/share/twomateos/events.json
Windows	%APPDATA%\twomateos\events.json
macOS	~/Library/Application Support/twomateos/events.json

Format:

{
  "events": [
    { "at": "2026-06-16T09:00:00", "status": "work" },
    { "at": "2026-06-16T09:45:00", "status": "wait" }
  ]
}

Statuses: work, wait, leave.

Project layout

app.py           — main window (PySide6)
store.py         — event log and interval calculation
stats_view.py    — statistics window (calendar + day timeline)
twomateos        — bash launcher (optional, add to PATH)
requirements.txt
assets/          — tray/window icons (green, yellow, red)

Test the storage logic:

python store.py

Planned

• Comparisons — day vs day and week vs week (efficiency trends, Wait share, etc.)
• Break reminders — gentle nudges to rest or step away when you have been at it too long
• Train whistle at 8 hours — a locomotive horn when combined tracked time reaches a full workday (8 h)