HSLViewer is a local desktop viewer for navigating Hamilton-style automation trace logs. It uses deterministic rules to group and color events, collapse related lines, search text or regular expressions, navigate timestamps, and inspect pipetting activity. Log contents stay on the computer running the app.
Project status: pre-release. A source-only
v0.1.0prerelease is archived on GitHub; current development targets0.2.0, and no signed Windows installer has been published yet.
HSLViewer combines deterministic parsing with synthetic regression fixtures to make complex automation traces easier to navigate. Quantitative time-saving claims require a reproducible task benchmark or documented user study.
| Goal | Recommended path |
|---|---|
| Use HSLViewer on Windows without installing Python | Download the Windows setup EXE from GitHub Releases when one is published |
| Use HSLViewer now on Windows | Follow Install from source on Windows below |
| Use HSLViewer on macOS or Linux | Follow Install from source on macOS or Linux below |
| Modify the code or run tests | Follow Contributor setup |
The Windows installer is the intended end-user experience: download one file,
double-click it, and optionally choose HSLViewer for .trc files. Source setup
is available on every targeted platform and is the working path while the
project remains pre-release.
This path does not require Git, Python, or administrator rights on the target computer.
-
Open the HSLViewer GitHub Releases page.
-
Open the newest release and download both:
HSLViewer-<version>-windows-x64-setup.exeSHA256SUMS.windows.txt
-
In the download folder, verify that the setup file has the hash listed in the checksum file:
Get-FileHash -Algorithm SHA256 .\HSLViewer-*-setup.exe Get-Content .\SHA256SUMS.windows.txt
-
Double-click the setup EXE.
-
Leave Choose HSLViewer as the default app for .trc files selected if you want file association.
-
If setup opens Windows Default Apps, select
.trcand confirm HSLViewer. -
Open HSLViewer from the Start menu or double-click a
.trcfile.
There is no published installer yet. If the Releases page has no setup EXE, use the source instructions below. The current local candidate is unsigned, so a future unsigned candidate may display an Unknown publisher or SmartScreen warning. Verify its checksum and GitHub provenance before running it.
The portable ZIP beside the installer needs no installation: extract it and
run HSLViewer\HSLViewer.exe. It does not register .trc files. See
Windows installation and .trc association
for silent deployment, exact default-app behavior, and uninstall details.
Install these first:
- Git
- Python 3.10, 3.11, 3.12, or 3.13 with Tk support
Python 3.14 is not supported by the current package metadata. Python 3.13 is the recommended choice for a new setup. Use a current installer from python.org and select a 3.13 release.
Verify the prerequisites before cloning on Windows:
git --version
py -3.13 --version
py -3.13 -m tkinterOn macOS or Linux, use the supported Python executable installed on that system, for example:
git --version
python3.13 --version
python3.13 -m tkinterThe Python version must be at least 3.10 and lower than 3.14. The final command should open a small Tk demonstration window; close it before continuing.
Open PowerShell or Command Prompt and run:
git clone https://github.com/Dalconzo/HSLViewer.git
cd HSLViewer
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\python.exe -m hslviewer --help
.\.venv\Scripts\python.exe -m hslviewer .\examples\synthetic_demo.trcThe last command opens the deliberately generated demonstration trace. The commands call the virtual environment directly, so PowerShell script execution policy and environment activation are not involved.
If py -3.13 says that Python 3.13 is unavailable, install Python 3.13 or
replace py -3.13 with an installed supported interpreter such as py -3.12.
Open Terminal and run the following. Substitute python3.12 if that is the
supported Python executable installed on your system.
git clone https://github.com/Dalconzo/HSLViewer.git
cd HSLViewer
python3.13 -m venv .venv
./.venv/bin/python -m pip install .
./.venv/bin/python -m hslviewer --help
./.venv/bin/python -m hslviewer examples/synthetic_demo.trcFor macOS, the current python.org macOS installers
include the Tk frameworks needed by tkinter. On Linux, install your
distribution's Python venv and Tk packages if python3.13 -m venv or
python3.13 -m tkinter fails; package names commonly include python3-venv
and python3-tk, but exact names depend on the distribution and Python version.
From the repository directory:
# Windows
.\.venv\Scripts\python.exe -m hslviewer
.\.venv\Scripts\python.exe -m hslviewer C:\path\to\run.trc# macOS or Linux
./.venv/bin/python -m hslviewer
./.venv/bin/python -m hslviewer /path/to/run.trcStarting without a path opens an empty viewer; use Open or Ctrl+O to
choose a file. The installed hslviewer console command is also available
inside the virtual environment, but python -m hslviewer makes the interpreter
being used explicit.
Open examples/synthetic_demo.trc before using a real trace. It is deliberately
generated and demonstrates:
- critical errors and warnings;
- user traces and timestamp navigation;
- literal and regular-expression search;
- collapsible category blocks and summaries;
- aspirate and dispense events; and
- dark and light appearance modes.
Use Ctrl+Shift+T or the Light command-bar toggle to switch appearance.
If the synthetic file loads, categories are colored, Find returns matches, and
the appearance changes without reloading, the desktop setup is working.
The Open dialog accepts .trc, .log, and .txt files. Classification is
tuned for Hamilton-style automation messages matching the deterministic rules
in hslviewer/rules.py. A matching extension alone does
not make an arbitrary log format semantically compatible.
| System | Installation | Current evidence |
|---|---|---|
| Windows 10/11 x64 | Setup EXE, portable ZIP, or source | Windows 11 build and Tk smoke tests; installer is configured for Windows 10 or newer |
| macOS with Python 3.10-3.13 and Tk | Source | Automated domain/package CI; manual desktop release verification remains open |
| Linux desktop with Python 3.10-3.13 and Tk | Source | Automated Ubuntu domain/package CI; manual desktop release verification remains open |
CI exercises Python 3.10 and 3.13 on Windows, macOS, and Ubuntu, plus Python
3.11 and 3.12 on Ubuntu. Runtime code has no third-party dependencies; it uses
the Python standard library, including tkinter. Packaging tools are optional,
pinned build dependencies.
Input is decoded as UTF-8 with replacement for malformed bytes. This preserves the rest of a damaged trace, but replacement characters can prevent an exact text match.
The command bar provides Open, Reload, Find, Go To, Jump, and Light controls. The legend can focus, collapse, expand, hide, or show each category. The gutter toggles an individual block. Lower controls expose compact lines, summary colors, hover highlighting, and collapsed-block stripes.
| Action | Shortcut |
|---|---|
| Open / reload | Ctrl+O / Ctrl+R |
| Find next / previous | Ctrl+F, then F3 / Shift+F3 |
| Go to line or time | Ctrl+G |
| Jump to a block | Ctrl+P |
| Inspect selected pipetting events | Ctrl+Shift+L |
| Toggle light/dark mode | Ctrl+Shift+T |
| Zoom in / out / reset | Ctrl+= / Ctrl+- / Ctrl+0 |
| Close the pipetting panel | Esc |
Timestamp navigation accepts 14:03:27.125 or a full value such as
2026-01-15 14:03:27.125. Pipetting analysis expects the event completion and
channel fields represented by the synthetic fixture.
HSLViewer stores per-log display state beside the trace as
<trace-name>.state.json. Removing only that sidecar resets collapse, focus,
visibility, and zoom state for that trace. The trace itself is never modified.
The light/dark choice is a user-level preference:
- Windows:
%APPDATA%\HSLViewer\settings.json - macOS:
~/Library/Application Support/HSLViewer/settings.json - Linux:
$XDG_CONFIG_HOME/hslviewer/settings.json, or~/.config/hslviewer/settings.jsonwhenXDG_CONFIG_HOMEis unset
To update an installer installation, run the newer setup EXE. To remove it, use Settings > Apps > Installed apps > HSLViewer > Uninstall.
To update a source installation, open the cloned repository and run:
# Windows
git pull --ff-only
.\.venv\Scripts\python.exe -m pip install --force-reinstall .# macOS or Linux
git pull --ff-only
./.venv/bin/python -m pip install --force-reinstall .A source installation is isolated inside the repository's .venv directory.
To remove it completely, delete the cloned HSLViewer directory after moving
any files you intentionally placed there. Real trace files should normally live
outside the repository.
Confirm that the clone URL is exactly
https://github.com/Dalconzo/HSLViewer.git and that GitHub is reachable. The
repository is public and cloning it does not require a GitHub account.
Run python --version, python3 --version, or py -0p on Windows. Create the
virtual environment with Python 3.10 through 3.13. Do not create it with Python
3.14 for this release.
Use python -m tkinter with the exact interpreter that will create the virtual
environment. On macOS, prefer a current python.org installer. On Linux, install
the matching Tk package from the distribution, commonly python3-tk.
Run the install command from the repository root, then launch with that same
virtual environment's Python. Do not mix a system pip with .venv Python.
# Windows repair
.\.venv\Scripts\python.exe -m pip install --force-reinstall .
.\.venv\Scripts\python.exe -m hslviewer --help# macOS/Linux repair
./.venv/bin/python -m pip install --force-reinstall .
./.venv/bin/python -m hslviewer --helpActivation is optional. Use .\.venv\Scripts\python.exe exactly as shown in
this README; no execution-policy change is required.
No signed release exists yet. Do not bypass SmartScreen for a file from an unknown location. For a trusted project candidate, first compare its SHA-256 hash with the checksum published beside it on GitHub.
Only the Windows installer registers file types. Open Settings > Apps >
Default apps, search for .trc, and select HSLViewer. A portable or source
installation can still open the file from HSLViewer's Open dialog.
Per-log state requires write access to the trace directory. The status bar reports a clear error when a sidecar cannot be saved. Appearance uses the user-settings path listed above and is independent of the trace directory.
The source contains bytes that are not valid UTF-8. Convert a copy to UTF-8 when exact matching is required; preserve the original evidence outside this repository.
Unknown messages intentionally fall back to System/Other. Compare the line
with hslviewer/rules.py. For pipetting details, select
the event completion lines including channel, position, labware, and volume.
HSLViewer processes logs locally and does not intentionally upload their contents. Logs may still contain sample identifiers, barcodes, user names, paths, instrument identifiers, or other confidential information.
- Do not commit or attach production traces to issues.
- Reproduce defects with
examples/synthetic_demo.trcor a new, deliberately generated minimal fixture. - Review screenshots for identifiers and paths before sharing them.
- Remember that
*.state.jsonsidecars and diagnostic logs can reveal source paths.
See synthetic fixture and privacy guidance.
- Parsing rules are format-specific. A typed custom-rule seam exists for domain callers, but there is no runtime plugin loader or rules editor. See the rules extension guide.
- Full-file reading and decoding complete in a worker before Tk insertion. Insertion, parsing, tagging, and pipetting enrichment then use time-sliced Tk callbacks; broad searches still scale with the complete file.
- Interactive GUI verification is not automated across all targeted operating systems and display scales.
- Regex behavior follows Python's
reengine; complex patterns can be slow. - A captured cross-platform screenshot/GIF, signed release, and clean-machine release evidence remain open. Treat the repository as pre-release software.
The recorded privacy-safe 100,000-line Windows trace first painted in 58.5 ms,
completed in 2.653 seconds, and kept the longest measured work slice to 10.7
ms. The 1,000,000-line trial missed the project guardrails, so million-line
interactive responsiveness is not claimed. These are single engineering
trials, not a user-task or time-savings benchmark. See
benchmarks/README.md for hardware, file sizes,
methodology, raw records, and caveats.
Complete the source installation above, then replace the normal installation with an editable one and run all tests:
# Windows
.\.venv\Scripts\python.exe -m pip install --editable .
.\.venv\Scripts\python.exe -m unittest discover -s tests -v# macOS or Linux
./.venv/bin/python -m pip install --editable .
./.venv/bin/python -m unittest discover -s tests -vThe standard-library suite includes unit and integration coverage plus a complete domain processing path through the synthetic trace. CI repeats the installation, launcher, tests, and wheel build across the supported Python matrix.
Repository layout:
hslviewer/- parser/domain code, controllers, and Tk presentationexamples/- deliberately generated demonstration datatests/- unit and integration testsscripts/- benchmark, development, and packaging helpersdocs/- installation, privacy, product, and architecture recordstodo/- scoped roadmap and progress notes
Read AGENTS.md before changing code. Record notable changes in
CHANGELOG.md, add or update a scoped todo/*.md item, and
never derive a committed fixture by redacting a production log.
On 64-bit Windows, the release builder can install its pinned PyInstaller dependency and Inno Setup, then create the standalone application, setup EXE, portable ZIP, and checksums:
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows_release.ps1 -Python .\.venv\Scripts\python.exe -BootstrapArtifacts appear under dist\windows. -Bootstrap uses winget to install
Inno Setup for the current user when it is missing. Run the resulting setup EXE
to test the same installation path intended for another computer.
The manual Build release candidate artifacts GitHub Actions workflow builds
and verifies the wheel and Windows artifacts but does not create a tag or
publish a GitHub Release. Publication requires the checks in
docs/release-checklist.md.
The current modernization used AI-assisted engineering tools for implementation, tests, documentation, and review. The maintainer remains responsible for product scope, technical decisions, verification, and release approval; generated output is not treated as evidence of domain correctness.
The privacy boundary and fixture-generation process are documented in Synthetic fixture design and privacy policy. Security concerns can be reported using the guidance in SECURITY.md.
HSLViewer is available under the MIT License. Copyright 2026 David Dalconzo.