Pstalker NPM | npm.io

About The Project

Built With

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. :)

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.

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 support for Windows
Add automated tests
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.

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!