wm-screenshooter 1.0.12

A sophisticated cross-platform screenshot tool with timer support and organization features

WorkMaster ScreenShooter

Screenshooter is a sophisticated cross-platform screenshot TUI application with timer support and organisation features. This modular Python application helps freelancers document their work with automatic (or manual) screenshots and pairs this with contemporaneous notes and the ability to create and email a PDF report to their clients.

Why?

"As a freelance developer I love to code and help solve my clients' problems. Much of my work is hourly requiring me to keep accurate logs and notes. I created ScreenShooter to keep track of sessions, projects and notes for clients allowing me to focus on the fun parts of coding and not the admin."

• Conor Ryan - ScreenShooter Creator

Note: ScreenShooter supports macOS (Linux and Windows are supported but are under beta testing).

Features

• Application lives in your terminal and can be left in the background tracking time while you focus on work
• Screenshot capture can be done automatically at regular intervals or manually when the user requests them.
• Flexibility in screenshot capture all displays, specific display or a dedicated window.
• Produce captions (which appear under given screenshots) or notes for communicating ideas to clients
• Ability to pause / resume when doing sensitive work
• Session based reporting system allows for flexibility and time management
• Built in client management features for sending reports and archiving finished projects
• Ability to generate and send reports to client after every session, day or when needed
• Upload reports to S3 bucket and generate link for clients to view
• Optional CLI for quicker session start
• Backup functionality to backup settings, database, and screenshots directory

Requirements

• Python 3.10 - 3.14
• macOS, Linux, or Windows
• For snippet drag-selection (w command):
  • PySide6-Essentials is optional and only required for GUI drag-selection.
• For desktop notifications (optional):
  • macOS: terminal-notifier (brew install terminal-notifier)
  • Linux: notify-send (usually pre-installed)
  • Windows: PowerShell (built-in)
• Email sending system (e.g. Brevo, SendGrid, Mailgun, etc.)
• S3 bucket (for remote report storage to make it easier to send reports to clients)
• Cloudflare KV (for custom link generation to make it easier to send reports to clients) (optional)

Installation

Option 1: Install from PyPI (Recommended)

pip install wm-screenshooter
screenshooter --version

To enable GUI snippet drag-selection (w) on top of the base install:

pip install "wm-screenshooter[snippet-gui]"

Option 2: Install from source (using uv)

1. Clone the repository and install the application using uv:

   git clone https://gitlab.com/workmaster/screenshooter.git
   cd screenshooter
   uv tool install .
   screenshooter --version
   

2. (Optional) enable GUI snippet drag-selection dependency:

   uv sync --extra snippet-gui
   

(Optional) Install notification support

Notification support is optional and will be disabled if not installed.

macOS:

brew install terminal-notifier # macOS

Linux: (Debian/Ubuntu)

sudo apt install libnotify-bin  # Debian/Ubuntu

Windows:

Not required as already built in.

Usage

Screenshooter can be used either via the command-line interface or via the interactive menu. Until you have created a client and project, you will need to use the interactive menu to set up your project and client.

Interactive Menu (first time use)

Below is the general flow for performing some of the common actions in the ScreenShooter program. Below will

How to take screenshots

TLDR; Skip to step 3 if you have already created a client and project.

1. On the main ScreenShooter screen press option 1.

2. As this is your first time using the application you will be prompted to create a client and a project. Do the following:

   • Enter the name of your client (no spaces) - eg: "Testing"
   • Press n for no to create a custom directory name for your client
   • Enter the Company Name - eg: "Testing Ltd"
   • Contact Name - eg: "John Doe"
   • Contact Email - eg: "[e-mail]"
   • Screenshot delivery method [local/email/cloud] (enter):
   • Notification preferences [all/important/none] (enter):
   • Reporting frequency [daily/weekly/monthly/none] (enter):
   • PDF security [none/password] (enter):
   • PDF page size [A4/letter] (enter):
   • Press enter to save the client information

3. You will now be asked to create a project. Do the following:

   • Enter the name of your project (no spaces) - eg: "BigProject"

4. (Start of Session)

   • Choose the display mode you want to use (press enter to use all):
   • Enter the timer duration in minutes - eg: 15
   • Type a note to start the session - eg: "Started working on BigProject"
   • Press enter to start the session

   A Countdown will start to take the first screenshot. (10 seconds).

   • The session is now running, the timer is counting down to the next screenshot.

   • Refer to the in-session commands below on how to interact with the session.

   • When you are finished with the session you can press 'q' to quit and take a final screenshot.

In-session commands

'n' - to add a note to the log
'c' - to add a caption to the last screenshot
's' - to take a manual screenshot now and reset timer
'o' - to open the last screenshot in Preview
'q' - to quit and take final screenshot
't' - to change the timer duration
'd' - to change the display mode
'p' - to pause the session for sensitive activities
'm' - to switch to manual mode (no timer)
'r' - to archive the last action (screenshot or note)
'e' - to list the last 5 actions
'l' - to open the current session log in TextEdit
'i' - to show time in session, today, and project total
'h' - for help
'z' - to cancel active countdowns 

CLI Command Structure

ScreenShooter uses a command-line interface with nested commands:

screenshooter                                   # Interactive menu
screenshooter client                            # List all clients
screenshooter client "ClientName"               # Manage specific client
screenshooter client "ClientName" projects      # List projects
screenshooter shoot --client "Name" --project "Project" [options]
screenshooter report                            # Interactive report generator
screenshooter --debug                           # Interactive menu; reports run with debug logs
screenshooter --debug report                    # Interactive report generator with debug logs
screenshooter report generate --client "Name" --project "Project"
screenshooter --debug report generate --client "Name" --project "Project"
screenshooter open logs|config                  # Open logs or config directories
screenshooter settings                          # Manage settings
screenshooter upgrade                           # Manage upgrade checks and notifications
screenshooter backup <settings|db|all> [--outputdir PATH]  # Create backups
screenshooter help                              # Show help information

Use the root --debug option when troubleshooting report generation, report S3/R2 upload links, or report email delivery. For now, debug behavior is only passed into the report workflow and does not enable debug behavior for clients, settings, screenshot capture, or backups.

For more information on the commands and options available, run screenshooter command --help for more information.

Directory Structure and Screenshot Storage

Screenshots are organized in the following structure:

~/WorkMaster_Screenshooter/
└── CLIENT_NAME/
    ├── client.json     # Client information and preferences
    └── PROJECT_NAME/
        ├── project.json
        ├── PROJECT_NAME_log.txt
        ├── reports/
        │   └── PROJECT_NAME_Report_YYYYMMDD_HHMMSS.pdf
        └── sessions/
            └── YYYY-MM-DD_HH-MM-SS/
                ├── session.log
                ├── session.json
                └── screenshots/
                    └── PROJECT_NAME_YYYY-MM-DD_HH-MM-SS_*.jpg

Above is the general structure of the application.

Notes

Email Support and Remote Report Storage

If you want to send screenshot reports to your client via email, configure the email settings in the settings menu. ScreenShooter supports:

• SMTP for traditional authenticated relay delivery
• Cloudflare Email Sending via Cloudflare's REST API

SMTP remains the default provider for backward compatibility.

Brevo is still a reasonable SMTP option with a generous free tier and simple setup. Cloudflare Email Sending is also supported if you have access to that product.

Many providers limit large attachments. To handle that, ScreenShooter can upload the report to an S3/R2 bucket and email a download link instead of attaching the PDF directly.

You can set up an S3 bucket and configure ScreenShooter to use it via the s3 setting in the settings menu. The S3 bucket will be used to store the screenshot reports and the link to the report will be generated and sent to your client via email.

For report delivery troubleshooting, run screenshooter --debug before generating and emailing a report. In report debug mode, the TUI shows the same report email and S3/R2 log events that are written during delivery, including upload details, link generation, Cloudflare KV output, and email transport status. Secrets such as SMTP passwords, S3 secret keys, Cloudflare API tokens, and authorization headers should not be printed.

Email Settings Compatibility

Existing SMTP-only settings files remain supported. Older settings.json files using the flat email structure such as:

{
  "email": {
    "enabled": true,
    "sender_email": "[e-mail]",
    "smtp_server": "smtp.example.com",
    "smtp_port": 587,
    "connection_security": "TLS",
    "username": "user",
    "password": "secret"
  }
}

continue to load as SMTP configuration automatically.

Updates

Checks for new versions of ScreenShooter are checked automatically every 7 days and can be checked manually with screenshooter upgrade check.

At this stage updates are not automatically installed. The update notification will ask you to update via pip / git.

Two update channels are available:

• release (default): checks GitLab releases for the latest mainline version available and informs the user every 7 days as configured.
• dev: performs commit-based checks against the configured branch head on the official upstream GitLab project on every execution. For more information on the dev branch, see the DEVELOPMENT file.

You can also skip or pin specific versions of ScreenShooter to prevent notifications for these or future versions (release channel only).

screenshooter upgrade check # Check for updates
screenshooter upgrade status # Show current channel/branch behavior
screenshooter upgrade channel <release|dev> # Set update channel
screenshooter upgrade branch <branch-name> # Set dev channel branch target
screenshooter upgrade settings --enable --frequency 7 # Configure checks
screenshooter upgrade skip <version> # Skip notifications for a specific version
screenshooter upgrade pin <version> # Pin to a specific version (release channel only)
screenshooter upgrade unpin # Remove pinned version (release channel only)

The upgrade itself is not automatically installed and requires you to manually download the latest version and install it.

If installing from PyPI:

pip install --upgrade wm-screenshooter
screenshooter --version

If installing from GitLab you can use the following command to install the latest version:

git pull
uv tool install .
screenshooter --version

Contributing

For contributor and branch workflow guidance (including dev/release upgrade channels), see docs/DEVELOPMENT.md.

Contributors should generally work from forks and open merge requests from fork branches rather than being given direct push access to the main repository. Dev-channel upgrade checks compare against the official upstream GitLab project, not arbitrary contributor forks.

Who Made This?

ScreenShooter is being developed by @conorjwryan as a part of the WorkMaster project. WorkMaster is a platform for freelancers to manage their work and clients. ScreenShooter is its companion application for capturing screenshots of their work when requested by clients.

The WorkMaster site is under closed development at the moment and is not ready for public use. More information will be available soon.

In the meantime, please checkout Conor's website and his GitLab for more of his projects.