wm-screenshooter 2.2.0

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
• Track project goals/tasks across sessions and include relevant progress in reports
• Ability to pause / resume when doing sensitive work
• Session based reporting system allows for flexibility and time management
• Session recovery can close sessions left unfinished after a crash or terminal failure
• 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
• CLI for quicker session start
• Backup functionality to back up settings, database, and screenshots directory
• Direct database backup command for timestamped raw SQLite .db snapshots before or outside schema migrations
• Workmaster sync: push local data (clients, projects, sessions, screenshots and notes) to the Workmaster remote dashboard and pull changes back (Find out more info here)
• Project goals and goal notes are included in Workmaster sync (pushed and pulled via the Workmaster API alongside sessions and screenshots).

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.

Note: If you're on macOS, this requires extra Screen Recording permission steps before screenshot capture works; see macOS Screen Recording permission.

Also, certain linux-based desktop environments will require a similar request approval too before you can screenshot programmatically. This is more determined by your setup and is not mentioned here. Please keep this in mind when using linux with screenshooter during first-use. If you experience issues this is the "most likely" reason.

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 - eg: "Testing"
   • Enter the Company Name - eg: "Testing Ltd"
   • Contact Name - eg: "John Doe"
   • Contact Email - eg: "[e-mail]"

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

   Note: For future settings when selecting the project you'll be asked whether you want to reuse the same display & timer settings.

   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
'g' - to manage project goals
'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 

Project goals

During a screenshot session, press g to open the project goals menu. Goals persist across every session in the current project. From the menu you can add goals, add progress notes, complete goals with an optional note, archive goals that are no longer applicable, and review current or recently closed goals. Relevant goal updates are included in session, day, and project reports when the database is enabled.

CLI Command Structure

Most commands are forgiving — supply as little or as much as you want, and ScreenShooter drops you into the interactive picker at the right step. Run screenshooter <command> --help on any command for its full flag list, or see docs/CLI.md for the full reference.

Common commands

Command	What it does
screenshooter	Interactive main menu.
screenshooter shoot	Interactive capture — pick client / project / mode.
screenshooter shoot --client="Big Client"	Drops into the project picker for that client.
screenshooter shoot --new	Create a new client and start capturing.
screenshooter report	Interactive report generator.
screenshooter report --client="X" --all --report-type=day --today	Today's day report across every active project under X.
screenshooter clients	List/manage clients.
screenshooter sessions recover	Close unfinished sessions left by crashes.
screenshooter backup all	ZIP backup of all data (S3 upload if configured).
screenshooter sync run	One Workmaster sync cycle.
screenshooter upgrade check	Check for updates.
screenshooter settings	Open the settings menu.
screenshooter help	Alias for screenshooter --help.

macOS Screen Recording permission

On macOS, Apple requires Screen Recording permission before a terminal app can capture screenshots. The permission is granted per terminal application, so approving Terminal does not automatically approve Ghostty, Cursor, iTerm, or another terminal.

ScreenShooter provides a disposable capture test to trigger Apple’s permission dialog before your first real session. After approving access, quit and reopen the terminal app before taking real screenshots. Follow the specific Apple popup to "Quit and Relaunch" as macOS does not apply the new permission to the already-running terminal process so screenshots may fail or capture the wrong thing until the app is restarted.

On a brand-new interactive setup, ScreenShooter offers to run this test automatically. Existing installs are not prompted. You can run the check later from any terminal app with screenshooter test shoot, from the screenshooter test diagnostics menu, or from the interactive menu under Extra Options > Tests/Diagnostics > Test screenshot capture.

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
                ├── .screenshooter_active_session.json  # present only while a session is running
                └── 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.

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

Updates to the Database

When an existing database has pending schema migrations, ScreenShooter prompts before applying database updates, creates a timestamped raw SQLite backup, and exits without applying migrations if the user declines. Direct DB backups are saved under ~/.config/screenshooter/db_migration_backups/.

Speed of Uploads (reports / backups)

The speed of uploads to remote S3/R2 buckets can be configured if needed to ensure maximum concurrency. A default of 8 threads has been chosen. It is not recommended to change this setting as how much benefit you receive from this determines on a combination of your CPU speed and available upload speed from your internet provider.

That said if you wish to, the setting can be found in the s3 settings.

Report and Backup Troubleshooting

Use the --debug option when troubleshooting report generation, report S3/R2 upload links, report email delivery, or backup event details. screenshooter --debug carries into reports and backups launched from the interactive menu, and the direct backup command also supports screenshooter backup all --debug. Sync has its own scoped debug flag: screenshooter sync run --debug.

"Expert" Mode

Use --expert when you need advanced interactive setup prompts. In expert mode, new-client creation can ask for a custom directory name and client preference overrides, and report generation shows the PDF optimization prompt. See CLI.md for information on the --expert argument.

WorkMaster Sync

The WorkMaster platform is currently under closed development. While the screenshooter side of the code remains open, the wider WorkMaster platform integration is closed. It is hoped that revenue derived from this platform will help support development of ScreenShooter for future. More information about the sync command can be found in the SYNC Document and more information on WorkMaster can be found at https://workmaster.app/.

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.