Powerful tool for real-time monitoring of Xbox Live players' activities.
New to Python or unsure what is installed? Follow the Python install walkthrough first.
Install from PyPI:
pip install xbox_monitorRun the setup wizard:
xbox_monitor --setupThe wizard asks for the target, the Microsoft Entra application credentials and optional notifications. Review the settings before saving them. See Setup & First Run for the application credentials, the first authorization and the required privacy settings.
For the manual single-file method, dependencies and upgrade commands, see Installation.
- Gaming activity: Track status, game starts, finishes and changes.
- Appear Offline: Detect gaming activity from title history when presence is hidden.
- Session statistics: Measure state and game durations, preserving statistics through short offline interruptions.
- Profile details: View XUID, status, platform, account tier, gamerscore and friends.
- Games and achievements: See recent games, playtime and earned achievements.
- Event alerts: Configure email, Discord and ntfy notifications independently.
- CSV history: Save reported activity with timestamps.
- Saved status: Retain monitoring state across restarts.
- Guided setup: Configure credentials and complete OAuth2 authorization with
--setup. - Preflight checks: Check readiness with
--doctorwithout writing files. - Flexible settings: Use config files, dotenv files, environment variables and command-line options.
- Terminal and runtime controls: Customize colours and adjust the running monitor through supported signals.
Use Quick Install & Run above for first-time setup. The table uses PyPI commands. For the manual script equivalents, see Run Individual Commands.
Replace the target placeholders with an Xbox gamertag, quoted when it contains spaces. Monitoring requires the Microsoft Entra application credentials described in the setup guide.
| I want to... | Run this |
|---|---|
| Configure the target, credentials and alerts | xbox_monitor --setup |
| Start monitoring with existing authentication | xbox_monitor "<xbox_gamertag>" |
| Check authentication, connectivity and one target | xbox_monitor --doctor "<xbox_gamertag>" |
| Enter or replace securely the Microsoft Entra application credentials | xbox_monitor --set-ms-app-credentials |
| Configure and test webhook alerts | Use the setup wizard or follow Webhook Settings |
| Save an SMTP password for email alerts | xbox_monitor --set-smtp-password |
| Send a test email | xbox_monitor --send-test-email |
| Save a new webhook URL | xbox_monitor --set-webhook-url |
| Send a test webhook | xbox_monitor --send-test-webhook |
| Show profile details once | xbox_monitor "<xbox_gamertag>" -i |
| Also show the friends list | xbox_monitor "<xbox_gamertag>" -i -f |
| Show recent achievements | xbox_monitor "<xbox_gamertag>" -i -r -n 10 |
| Write every change to a CSV file | xbox_monitor "<xbox_gamertag>" -b changes.csv |
| Use a specific configuration and secrets file | xbox_monitor --config-file xbox_monitor.conf --env-file .env "<xbox_gamertag>" |
| List every supported command-line flag | xbox_monitor --help |
Complete First Authorization before relying on Doctor. Doctor checks saved tokens and does not create them.
The monitored account must expose the activity described in User Privacy Settings.
Running the tool with no arguments offers the wizard if you have not saved an account. If an account is already saved, it starts monitoring that account.
The tool runs until interrupted (Ctrl+C). Use tmux or screen for persistence and run multiple copies to monitor several accounts.
For the application credentials, the first authorization, saved accounts and notification setup, see the full Setup & First Run guide.
For time zone, TLS verification, email and webhook setup, see Configuration. For notification choices, user information commands and output files, see Usage.
If a run fails, start with Doctor Preflight.
Full documentation is available at misiektoja.github.io/xbox_monitor:
| Page | What it covers |
|---|---|
| Installation | Python walkthrough, PyPI or manual installation, upgrades |
| Setup & First Run | Setup wizard, Microsoft Entra application credentials, the first authorization, privacy settings |
| Configuration | Config file, time zone, SMTP, webhooks, TLS verification, storing secrets, check intervals |
| Usage | Monitoring mode, user information mode, notifications, CSV export, signals, terminal output |
| Troubleshooting | --doctor preflight checks, what to do when something fails, --verbose and --debug output |
| Testing | Running the offline suite, the linter and the docs build |
| About | Change log, contributing, security, license, support |
See RELEASE_NOTES.md.
Bug reports, documentation fixes and code contributions are welcome. See CONTRIBUTING.md for the development setup, the checks CI enforces and what a change needs before it is merged. Participation is covered by the Code of Conduct.
Report a suspected vulnerability privately through GitHub security advisories, never as a public issue. SECURITY.md covers the reporting process, the supported versions and the security posture of stored credentials and configuration loading.
- misiektoja (@misiektoja)
Licensed under GPLv3. See LICENSE. Dependency licenses are listed in THIRD_PARTY_NOTICES.md.
Questions, bug reports and vulnerability reports each have a place, listed in SUPPORT.md.
If the project is useful to you, you can support its development through GitHub Sponsors or Buy Me a Coffee.