pStalker

pStalker is a CLI time-tracking tool for Linux, with future support planned for other OS. It tracks time spent on desktop apps from installation, continuing on each boot. Users can view usage reports for various timeframes (today, last 7 days, last month), can exclude specific apps as needed and export the usage data to CSV and JSON.
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

(back to top)

Built With

(back to top)

Supported Operating Systems

Operating System	Support Level
Linux (X11)	Full Support ✅
Linux (GNOME)	Requires Extension ✅
Windows	Not Yet Supported ❌
macOS	Not Yet Supported ❌

Tested Distributions:

• Manjaro GNOME Wayland: Tested and supported. ✅
• Ubuntu 22 GNOME X11: Tested and supported. ✅

Getting Started

Follow the instructions below to set up pStalker on your local Linux machine.

Prerequisites

Ensure that you have the following installed on your system:

• Python
• Node.js

Installation

⚠️ Warning for Linux Users:

• GNOME Users: You must install the Window Calls Extended extension for pStalker to function properly.
• Autostart Configuration: Ensure your Linux distribution uses the ~/.config/autostart/ directory to run scripts on login; otherwise, pStalker won't work.
• Privileges: You might need to use sudo to install pStalker.

Install pStalker globally using npm:

 npm install -g --foreground-scripts pstalker

Thats it, pStalker will automatically configures itself to start on boot by placing a script in the ~/.config/autostart/ directory.

🔒 Privacy Note: Rest assured, pStalker does not collect any type of user data. You can review the code to confirm our commitment to your privacy. :)

(back to top)

Usage

Run the tool with the following command:

pstalker

The following is a representation of the pStalker CLI menu and its options:

pStalker CLI
├── Main Menu
│   ├── Enable Tracking
│   │   └── Enables tracking both now and on boot. Re-runs the installer script; may require sudo.
│   ├── Disable Tracking
│   │   └── Disables tracking both now and on boot. Removes tool-related files; database remains unchanged; may require sudo.
│   │ 
│   ├── Show Apps Usage
│   │   ├── Show Today
│   │   │   └── Displays usage data for today.
│   │   ├── Show Last Week
│   │   │   └── Displays usage data for the last 7 days.
│   │   ├── Show Last Month
│   │   │   └── Displays usage data for the last 30 days.
│   │   ├── Show Last Year
│   │   │   └── Displays usage data for the last 365 days.
│   │   ├── Show Specific Date
│   │   │   └── Displays usage data for a specific day.
│   │   └── Show Date Range
│   │       └── Displays usage data for a specific date range.
│   │ 
│   ├── Manage Apps
│   │   ├── Show Apps List
│   │   │   └── Lists all apps detected at least once.
│   │   ├── Include Apps
│   │   │   └── Re-includes apps that were previously excluded.
│   │   ├── Exclude Apps
│   │   │   └── Excludes apps from tracking.
│   │   └── Delete Apps Usage History
│   │       └── Deletes usage history for one or more apps.
│   │ 
│   ├── Export Data
│   │   ├── Export to CSV
│   │   │   └── Exports usage data to a CSV file.
│   │   └── Export to JSON
│   │       └── Exports usage data to a JSON file.
│   │ 
│   ├── Backup & Restore
│   │   ├── Create Backup
│   │   │   └── Creates a backup of the current database.
│   │   └── Restore from Backup
│   │       └── Lists available backups and allows restoring from a selected backup file.
│   │ 
│   ├── Help
│   │   └── Displays the help menu for the current section.
│   └── Exit
│       └── Exits the tool.

(back to top)

Roadmap

• Enable selecting a specific day for generating reports
• Enable selecting a date range for generating reports
• Enable deleting all usage history for a specific app
• Allow exporting data to a CSV file
• Allow exporting data to a JSON file
• Enable importing and exporting database backups
• Add automated tests
• Add support for Windows (Once the Repository reaches 50 stars)
• Develop a GUI using Electron for viewing data on Linux and Windows. (Once the Repository reaches 100 stars)

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make pStalker better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Gianluca Iavicoli - Linkedin - info@gianlucaiavicoli.dev

(back to top)

Acknowledgments

Special thanks to the resources and tools that helped make this project possible:

• Inquirer.js
• node-real-idle
• node-active-window
• window-calls-extended

(back to top)