wm-screenshooter 1.0.10

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 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

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 the screenshot reports to your client via email this requires you to set use a bulk email sending system. ScreenShooter supports this via the email setting in the settings menu.

Brevo is recommended as it has a generous free tier and is easy to set up. The one catch with these bulk email senders is that they often don't allow for large attachments. This is why ScreenShooter allows you to upload the report to an S3 bucket and then generate a link to the report.

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.

Updates

Updates to ScreenShooter are checked automatically at startup and can be checked manually with screenshooter upgrade check.

Two update channels are available:

• release (default): checks GitLab releases and uses cached checks.
• dev: checks the configured branch head commit on every run (no cache reads).

When running from a local git checkout (for example via uv run screenshooter), dev checks use local HEAD as the current commit source.

You can also skip or pin specific versions of ScreenShooter to prevent notifications for these or future versions.

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
screenshooter upgrade unpin # Remove pinned version

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.

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.