Keystroke Counter

A privacy-focused CLI tool that counts your keyboard activity without storing any actual keypress data. Perfect for tracking typing productivity and habits!

Getting Started

cargo install keystr
keystr init
keystr start

If you face installation issues on Debian/Ubuntu, do the Prerequisites

• Only counts keystrokes - no actual key data is captured or stored
• Fully transparent - all data stored locally
• Open source - audit the code yourself
• No network access - everything stays on your machine

Features

• Track total, daily, weekly, and monthly keystroke counts
• Runs in detached background mode
• Export statistics to text files
• Beautiful colored terminal output
• Simple configuration in your config directory

Prerequisites

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install libx11-dev libxtst-dev libevdev-dev libxcb1-dev

Linux (Fedora/RHEL/CentOS)

sudo dnf install libX11-devel libXtst-devel libevdev-devel libxcb-devel

Linux (Arch)

sudo pacman -S libx11 libxtst libevdev libxcb

Installation

1. Clone the repository:

git clone https://github.com/thembinkosimkhonta01/keystr
cd keystr

2. Build the project:

make build
# or
cargo build --release

3. (Optional) Install globally:

make install
# or
cargo install --path .

Or copy the binary to your PATH:

sudo cp target/release/keystr /usr/local/bin/

📖 Usage

Initialize

Set up the configuration directory and data files:

keystr init

Start Monitoring

Start the background daemon (runs in detached mode):

keystr start

The daemon will run in the background and count keystrokes silently.

Check Status

Check if monitoring is currently running:

keystr status

Stop Monitoring

Stop the background daemon:

keystr stop

View Statistics

Show all statistics (default shows daily for last 7 days):

keystr stats

Show daily statistics:

keystr stats --daily

Show weekly statistics:

keystr stats --weekly

Show monthly statistics:

keystr stats --monthly

Combine flags:

keystr stats --daily --weekly --monthly

Export Statistics

Export statistics to a text file:

keystr export

Custom output file:

keystr export --output my_stats.txt

Reset Statistics

Clear all statistics (requires confirmation):

keystr reset

📁 Configuration

All data is stored in your system's config directory:

• Linux: ~/.config/keystr/
• macOS: ~/Library/Application Support/keystr/
• Windows: C:\Users\<User>\AppData\Roaming\keystr\

Files:

• data.json - Stores keystroke counts and statistics
• daemon.pid - Process ID of running daemon (when active)

🐛 Troubleshooting

"Permission denied" errors on Linux

The daemon might need elevated permissions to monitor keyboard events. Try:

sudo keystr start

Daemon won't start

1. Check if it's already running: keystr status
2. Check system logs for errors
3. Try stopping and starting again:

keystr stop
keystr start

Build fails with X11 errors

Make sure you've installed the X11 development libraries (see Prerequisites section).

📊 Example Output

=== Keystroke Statistics ===
Total Keystrokes: 45,782

📅 Daily Stats (Last 7 Days):
  2025-10-07 8,234 keystrokes
  2025-10-06 7,891 keystrokes
  2025-10-05 6,543 keystrokes
  2025-10-04 9,012 keystrokes
  2025-10-03 5,678 keystrokes
  2025-10-02 4,321 keystrokes
  2025-10-01 4,103 keystrokes

📊 Weekly Stats (Last 7 Days):
  45,782 keystrokes

📈 Monthly Stats (Last 30 Days):
  45,782 keystrokes

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This tool is designed for personal productivity tracking only. Always respect privacy laws and obtain proper consent before monitoring any keyboard activity that isn't your own.