Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kalix127/pstalker
pStalker is a CLI-only time tracking tool that monitors the time spent on desktop applications.
https://github.com/kalix127/pstalker
app-usage cli cli-tool linux time-tracking-tool tracker windows
Last synced: 18 days ago
JSON representation
pStalker is a CLI-only time tracking tool that monitors the time spent on desktop applications.
- Host: GitHub
- URL: https://github.com/kalix127/pstalker
- Owner: kalix127
- License: mit
- Created: 2024-08-24T01:36:55.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-12-12T04:25:05.000Z (27 days ago)
- Last Synced: 2024-12-20T19:19:46.087Z (19 days ago)
- Topics: app-usage, cli, cli-tool, linux, time-tracking-tool, tracker, windows
- Language: JavaScript
- Homepage:
- Size: 234 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
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
## About The Project
[![Product Name Screen Shot][product-screenshot]](https://github.com/kalix127/pStalker)### Built With
![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=F7DF1E) ![NodeJS](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white) ![Shell Script](https://img.shields.io/badge/shell_script-%23121011.svg?style=for-the-badge&logo=gnu-bash&logoColor=white) ![Python](https://img.shields.io/badge/python-%2314354C.svg?style=for-the-badge&logo=python&logoColor=white) ![SQLite](https://img.shields.io/badge/sqlite-%2307405e.svg?style=for-the-badge&logo=sqlite&logoColor=white)## 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](https://extensions.gnome.org/extension/4974/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:
```bash
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:
```bash
pstalker
```The following is a representation of the pStalker CLI menu and its options:
```md
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
- [x] Enable selecting a specific day for generating reports
- [x] Enable selecting a date range for generating reports
- [x] Enable deleting all usage history for a specific app
- [x] Allow exporting data to a CSV file
- [x] Allow exporting data to a JSON file
- [x] 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](https://github.com/kalix127/pStalker/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!
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.
## Contact
Gianluca Iavicoli - [Linkedin](https://www.linkedin.com/in/gianluca-iavicoli-684b32262) - [email protected]
## Acknowledgments
Special thanks to the resources and tools that helped make this project possible:
* [Inquirer.js](https://github.com/SBoudrias/Inquirer.js)
* [node-real-idle](https://github.com/paymoapp/node-real-idle)
* [node-active-window](https://github.com/paymoapp/node-active-window)
* [window-calls-extended](https://extensions.gnome.org/extension/4974/window-calls-extended/)[product-screenshot]: images/screenshot.png