Timekeep

A process activity tracker, it runs as a background service recording start/stop events for select programs and aggregates active sessions, session history, and lifetime program usage. Now has WakaTime/Wakapi integration.

Table of Contents

• Features
• How It Works
• Usage
• Installation
• WakaTime/Wakapi
• File Locations
• Contributing & Issues
• License

Features

• Track programs by executable basename (e.g., notepad.exe, code, bash)
• Start/stop detection:
  • Windows: WMI PowerShell subscription
  • Linux: /proc polling with exe/cmdline-based identity
• Active session aggregation across multiple PIDs
• Session history and total lifetime durations
• CLI for managing tracked programs
• WakaTime integration allows for tracking external program usage alongside your IDE/web-browsing stats

How It Works

• Windows: Embeds a PowerShell script to subscribe to WMI process start/stop events. Runs a pre-monitoring script to find any tracked programs already running on service start

• Linux: Polls /proc, resolves process identity via /proc/<pid>/exe (readlink) -> fallback to /proc/<pid>/cmdline -> last-resort /proc/<pid>/comm, then matches by basename. It polls at a configurable time.Duration value, defaulting to 1s. To catch accidental transient misses, a grace period is granted which is also a configurable value. If a PID is no longer found, or missed when polling, the process will keep being tracked until (poll_interval * poll_grace). For example, default values are poll_interval = 1s and poll_grace = 3; If a PID is missed, it’s removed after poll_interval × poll_grace. 0 grace time is allowed if desired.

• Session model: A session begins when the first process for a tracked program starts. Additional processes (ex. multiple windows) are added to the active session. The session ends only when the last process terminates, giving an accurate picture of total time with that program.

Usage

Full command reference: Commands

Quick Start

timekeep add notepad.exe --category notes # Add notepad
timekeep ls               # List currently tracked programs
 • notepad.exe
timekeep info notepad.exe # Basic info for program sessions
 • Category: notes
 • Current Lifetime: 19h 41m
 • Total sessions to date: 4
 • Last Session: 2025-09-26 11:25 - 2025-09-26 11:26 (21 seconds)
 • Average session length: 4h 55m
timekeep history notepad.exe  # Session history for program
  notepad.exe | 2025-09-26 11:25 - 2025-09-26 11:26 | Duration: 21 seconds
  notepad.exe | 2025-09-24 13:49 - 2025-09-24 13:50 | Duration: 39 seconds
  notepad.exe | 2025-09-23 11:18 - 2025-09-23 11:19 | Duration: 56 seconds
  notepad.exe | 2025-09-22 13:08 - 2025-09-23 08:48 | Duration: 19h 39m

Note: Program category not required for local tracking. Required for WakaTime integration.

Installation

Prerequisites

• Go 1.24+ (if building from source)
• Windows: Administrator privileges for service installation
• Linux: sudo privileges for systemd service setup

Method 1: Install script

1. Download latest release ZIP from Releases
2. Extract ZIP
3. Run the appropriate install script:

• Windows: Double-click 'install.bat'
• Linux: chmod +x install.sh && sudo ./install.sh

Method 2: Build from Source

Windows

# Clone and build
git clone https://github.com/jms-guy/timekeep
cd timekeep
GOOS=windows go build -o timekeep-service.exe ./cmd/service
GOOS=windows go build -o timekeep.exe ./cmd/cli

# Install and start service (Run as Administrator)
sc.exe create timekeep binPath= "\"C:\Path\to\timekeep-service.exe\"" start= auto 
sc.exe start timekeep

# Verify service is running
Get-Service -Name "timekeep"

Test using CLI:

.\timekeep.exe status # Check if the service is responsive

To include shell completion:

New-Item -Force -ItemType Directory (Split-Path $PROFILE) | Out-Null
$comp = Join-Path (Split-Path $PROFILE) 'timekeep.ps1'
timekeep completion powershell > $comp
if (-not (Select-String -Path $PROFILE -SimpleMatch $comp -Quiet)) { Add-Content $PROFILE "`n. $comp" }
. $PROFILE

If you encounter issues running scripts in PowerShell, bypass the ExecutionPolicy with:

powershell -ExecutionPolicy Bypass

for a single terminal session, or loosen restrictions with:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Linux

# Clone and build
git clone https://github.com/jms-guy/timekeep
cd timekeep
GOOS=linux go build -o timekeepd ./cmd/service  
GOOS=linux go build -o timekeep ./cmd/cli

# Install binaries
sudo install -m 755 timekeepd /usr/local/bin/
sudo install -m 755 timekeep /usr/local/bin/

# Database directory
mkdir -p ~/.local/share/timekeep

# Set service capabilities, for /proc read permissions
sudo setcap cap_dac_read_search,cap_sys_ptrace+ep /usr/local/bin/timekeepd

# Set user/group variables
USER_NAME=$(whoami)
GROUP_NAME=$(id -gn)

# Create socket directory and set permissions
sudo mkdir -p /var/run/timekeep
sudo chown "$USER_NAME":"$GROUP_NAME" /var/run/timekeep
sudo chmod 755 /var/run/timekeep

# Create systemd service
sudo tee /etc/systemd/system/timekeep.service > /dev/null <<EOF
[Unit]
Description=TimeKeep Process Tracker
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/timekeepd
StandardOutput=journal
StandardError=journal
KillMode=process
Restart=always
RestartSec=2s
User=$USER_NAME
Group=$GROUP_NAME

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable timekeep.service
sudo systemctl start timekeep.service

# Check status
sudo systemctl status timekeep

Test using CLI:

timekeep status # Check if the service is responsive

To include shell completion:

timekeep completion bash | sudo tee /etc/bash_completion.d/timekeep >/dev/null
source /etc/bash_completion

Uninstalling

To clean up logs/config/database, file locations are available here.

Windows

sc.exe stop timekeep
sc.exe delete timekeep

Linux

sudo systemctl disable --now timekeep
sudo rm /etc/systemd/system/timekeep.service
sudo rm /usr/local/bin/timekeepd /usr/local/bin/timekeep
sudo systemctl daemon-reload

WakaTime/Wakapi

WakaTime

Timekeep now integrates with WakaTime, allowing users to track external program usage alongside their IDE and web-browsing stats. Timekeep does not track activity within these programs, only when these programs are running.

To enable WakaTime integration, users must:

1. Have a WakaTime account
2. Have wakatime-cli installed on their machine

Enable integration through timekeep. Retrieve your API key from your WakaTime profile settings. Set your WakaTime API key and wakatime-cli path either directly in the Timekeep config file, or provide them through flags:

timekeep wakatime enable --api_key "YOUR_KEY" --cli_path "wakatime-cli_PATH"

{
  "wakatime": {
    "enabled": true,
    "api_key": "API_KEY",
    "cli_path": "PATH",
    "global_project": "PROJECT"
  }
}

The wakatime-cli path must be an absolute path.

C:\Path\To\.wakatime\wakatime-cli.exe

/home/user/wakatime-cli-linux-amd64

Complete WakaTime setup example

timekeep wakatime enable --api_key "YOUR_KEY" --cli_path "wakatime-cli_PATH"

timekeep add photoshop.exe --category "designing" --project "UI Design"

Check WakaTime current enabled/disabled status:

timekeep wakatime status

Disable integration with:

timekeep wakatime disable

Categories

After enabling, wakatime-cli heartbeats will be sent containing tracking data for given programs. Note, that only programs added to Timekeep with a given category will have data sent to WakaTime.

timekeep add notepad.exe --category "notes"

If no category is set for a program, it will still be tracked locally, but no data for it will be sent out.

List of categories accepted(defined here):

"Category of this heartbeat activity. Can be \"coding\", \"ai coding\","+
			" \"building\", \"indexing\", \"debugging\", \"learning\", \"notes\","+
			" \"meeting\", \"planning\", \"researching\", \"communicating\", \"supporting\","+
			" \"advising\", \"running tests\", \"writing tests\", \"manual testing\","+
			" \"writing docs\", \"code reviewing\", \"browsing\","+
			" \"translating\", or \"designing\".

Projects

Timekeep has no automatic project detection for WakaTime. Users may set a global project for all programs to use in the config, or via the command:

timekeep config --global_project "YOUR-PROJECT"

Users can also set project variables on a per-program basis:

timekeep add notepad.exe --category "notes" --project "Timekeep"

Program-set project variables will take precedence over a set Global Project. If no project variable is set via the global_project config or when adding programs, WakaTime will fall back to default "Unknown Project".

Users can update a program's category or project with the update command:

timekeep update notepad.exe --category "planning" --project "Timekeep2"

Wakapi

Similar to WakaTime, users can also allow their program activity to be tracked via Wakapi. The commands and structures are very similar, to enable integration you need your Wakapi API key as well as the address to your running Wakapi server, provided through either command flags or editing the config file.

timekeep wakapi enable --api_key "YOUR_KEY" --server "https://wakapi.example.com"

or for local instances:

timekeep wakapi enable --api_key "YOUR_KEY" --server "http://127.0.0.1:3000"

timekeep wakapi disable

timekeep wakapi status

{
  "wakapi": {
    "enabled": true,
    "api_key": "API_KEY",
    "server": "ADDRESS",
    "global_project": "PROJECT"
  }
}

The global project variable for Wakapi can be altered manually in the config file. Note: Using timekeep config --global_project sets both WakaTime and Wakapi global projects to the same value. For separate projects, edit the config file directly.

File Locations

• Logs

  • Windows: C:\ProgramData\Timekeep\logs
  • Linux: journal -- journalctl -u timekeep

• Config

  • Windows: C:\ProgramData\Timekeep\config
  • Linux: ~/.config/timekeep
  • Config structure:

  {
    "wakatime": {
      "enabled": true,
      "api_key": "API_KEY",
      "cli_path": "PATH",
      "global_project": "PROJECT"
    },
    "wakapi": {
      "enabled": true,
      "api_key": "API_KEY",
      "server": "ADDRESS",
      "global_project": "PROJECT"
    },
    "poll_interval": "1s", 
    "poll_grace": 3, 
  }

  • Update config manually & refresh service, or via command line:

  timekeep config --poll_interval "2.5s" --poll_grace 2

• Database

  • Windows: C:\ProgramData\Timekeep
  • Linux: ~/.local/share/timekeep

Contributing & Issues

To contribute, clone the repo with git clone https://github.com/jms-guy/timekeep. Please fork the repository and open a pull request to the main branch. Run tests from base repo using go test ./...

If you have an issue, please report it here.

License

Licensed under MIT - see LICENSE.