qurtail 1.0.0__tar.gz

qurtail-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mattie Casper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qurtail-1.0.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: qurtail
+Version: 1.0.0
+Summary: Follow logs while compacting conservative repeated patterns
+Author: Mattie Casper
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Mattie/qurtail
+Project-URL: Issues, https://github.com/Mattie/qurtail/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+# qurtail can Quell Unwanted Repetition
+
+Long-running logs have a bad habit of saying the same thing thousands of times with a new
+timestamp attached. That is tolerable when you're watching a terminal. It gets expensive and
+fairly useless when a coding agent has to read the whole thing.
+
+`qurtail` gives you or your agent a smaller view of the stream. It prints the first example of a repeated pattern, shows dots while more copies arrive, and closes the run with an exact count. Warnings, errors, status changes, unfamiliar numbers, and multiline diagnostics stay visible.
+
+```text
+> qurtail -F -n 50 app.log
+2026-08-08T12:00:00Z INFO refreshed cache request_id=715a
+........ [8 similar in 1s]
+2026-08-08T12:00:09Z ERROR cache refresh failed: connection refused
+..... [5 similar before stop]
+```
+
+A silent monitor is hard to distinguish from a stuck one. Qurtail provides the dots by default as a small sign of life, but you can change that with `--dot-every`.
+
+## Install it
+
+Qurtail requires Python 3.11 or newer. It has no runtime dependencies.
+
+
+To install from PyPI:
+```bash
+uv tool install qurtail
+# or
+pipx install qurtail
+```
+
+To install from GitHub:
+```bash
+git clone https://github.com/Mattie/qurtail.git
+cd qurtail
+uv tool install .
+```
+
+Or use `pipx` after cloning:
+
+```bash
+pipx install .
+```
+
+To run the repository once without installing it:
+
+```bash
+uvx --from . qurtail -F -n 50 app.log
+```
+
+## Follow along!
+
+```bash
+qurtail -F -n 50 app.log
+```
+
+`-n` is the number of existing lines to read when the file opens. The default is 10, like `tail`.
+Both `-f` and `-F` continue following when the file is truncated, replaced, or rotated.
+
+Leave off the follow flag when you want to compact a file once and exit:
+
+```bash
+qurtail app.log
+```
+
+For a particularly busy log, print one dot for every ten suppressed records:
+
+```bash
+qurtail -F --dot-every 10 app.log
+```
+
+Every suppressed record produces one dot by default. Qurtail buffers those dots into short runs
+before writing them, then closes the run with the exact repeat count and a newline when the pattern
+changes, 30 seconds pass, or monitoring stops. It doesn't redraw old terminal lines with
+backspaces or carriage returns, so captured output stays readable too.
+
+## Run a command
+
+If qurtail is launching the noisy command, use `run`:
+
+```bash
+qurtail run -- pytest -q
+```
+
+Everything after `--` is passed directly to the child command. There is no implicit shell in the
+middle interpreting pipes, substitutions, or redirects.
+
+Standard output and standard error are combined and sent through the same conservative reducer.
+Qurtail returns the child's success or failure status. If you interrupt qurtail, it interrupts and
+reaps the child process before exiting. A failed test run should still look like a failed test run;
+saving screen space is no excuse for losing the exit code.
+
+The same form works for container logs:
+
+```bash
+qurtail run -- docker logs -f api
+```
+
+```bash
+qurtail run -- kubectl logs -f deploy/api --timestamps
+```
+
+When another command already owns the pipeline, qurtail can read standard input:
+
+```bash
+producer 2>&1 | qurtail
+```
+
+With no filename and no `run` subcommand, it reads until standard input closes.
+
+Run `qurtail -h` for the complete command reference.
+
+## What counts as repetition?
+
+Qurtail uses bounded per-stream state to index patterns it has already printed. It recognizes a
+small, corpus-proven set of values that commonly change without changing the meaning of a log
+line:
+
+- timestamps
+- UUIDs
+- request, trace, and span IDs
+- standard JSON log metadata
+- stable container and service prefixes
+
+The matcher errs on the side of printing a line. It doesn't use a broad fuzzy-similarity score,
+since that is a good way to make an important number disappear. These two lines are different and
+both remain visible:
+
+```text
+replication lag is 1 second
+replication lag is 900 seconds
+```
+
+Unknown shapes, ambiguous values, and unfamiliar changing values also print in full. The same goes
+for malformed structured records and multiline content qurtail isn't sure how to join.
+
+Warning, error, and fatal transitions stay visible, along with HTTP status changes and changed
+structured error payloads. Same-level errors with different details get their own full record.
+Tracebacks, stack traces, and other multiline diagnostic blocks stay together. Repeated identical
+errors may be summarized after one complete example.
+
+Every suppressed record increments the count for its visible pattern. Suppressed records don't
+teach the matcher new patterns, so a hidden record cannot become the hidden example that makes some
+later line disappear.
+
+### Optional aggressive matching
+
+Conservative matching remains the default. When changing values still make repetitive output look
+unique, `--aggressive` also treats these hexadecimal, path, and long-integer values as noise.
+
+Keep in mind that sometimes ports, years, durations, byte counts, identifiers, and affected paths can all matter. Only use `--aggressive` when those values are noise.
+
+## Keep the raw output if you'll need it
+
+Qurtail is just a viewing helper to reduce noise. You may still want the followed stream captured.
+
+When qurtail runs the child command, use `--raw-log` to keep the raw text:
+
+```bash
+qurtail run --raw-log api.raw.log -- docker logs -f api
+```
+
+(The raw-log path must be new. To deliberately replace an existing log, add `--overwrite`.)
+
+For a pipe, keep the raw copy before the stream reaches qurtail:
+
+```bash
+docker logs -f api 2>&1 | tee api.raw.log | qurtail
+```
+
+Without `--raw-log`, qurtail doesn't create a transcript or keep a second copy.
+
+## What qurtail doesn't do
+
+Qurtail compacts a live local stream while it passes through. It doesn't store logs unless you ask.
+
+## Benchmarks and tests
+
+The benchmark suite includes regression fixtures, held-out monitoring episodes, and large-corpus
+runs. Installed-command smoke tests run on Linux, macOS, and Windows.
+
+See [`benchmarks/README.md`](benchmarks/README.md) for more. If you have good log data you want to share, please open an issue or pull request. The more diverse the corpus, the better qurtail can be updated to recognize repetition.
+
+## Agent skill
+
+The included `qurtail-fluency` skill makes qurtail the default for verbose tests, builds,
+installers, development servers, services, container and Kubernetes workloads, and followed logs.
+
+## Changelog
+
+### 1.0.0
+
+- Added opt-in aggressive matching for long integers, prefixed hexadecimal values, and absolute
+  paths.
+- Protected existing raw transcripts by default and added an explicit overwrite option.
+- Kept corpus-integrity verification byte-exact across Linux, macOS, and Windows.
+- Included the complete MIT license in source and built distributions.
+
+## License
+
+[MIT License](LICENSE.md)

qurtail-1.0.0/README.md

@@ -0,0 +1,200 @@
+# qurtail can Quell Unwanted Repetition
+
+Long-running logs have a bad habit of saying the same thing thousands of times with a new
+timestamp attached. That is tolerable when you're watching a terminal. It gets expensive and
+fairly useless when a coding agent has to read the whole thing.
+
+`qurtail` gives you or your agent a smaller view of the stream. It prints the first example of a repeated pattern, shows dots while more copies arrive, and closes the run with an exact count. Warnings, errors, status changes, unfamiliar numbers, and multiline diagnostics stay visible.
+
+```text
+> qurtail -F -n 50 app.log
+2026-08-08T12:00:00Z INFO refreshed cache request_id=715a
+........ [8 similar in 1s]
+2026-08-08T12:00:09Z ERROR cache refresh failed: connection refused
+..... [5 similar before stop]
+```
+
+A silent monitor is hard to distinguish from a stuck one. Qurtail provides the dots by default as a small sign of life, but you can change that with `--dot-every`.
+
+## Install it
+
+Qurtail requires Python 3.11 or newer. It has no runtime dependencies.
+
+
+To install from PyPI:
+```bash
+uv tool install qurtail
+# or
+pipx install qurtail
+```
+
+To install from GitHub:
+```bash
+git clone https://github.com/Mattie/qurtail.git
+cd qurtail
+uv tool install .
+```
+
+Or use `pipx` after cloning:
+
+```bash
+pipx install .
+```
+
+To run the repository once without installing it:
+
+```bash
+uvx --from . qurtail -F -n 50 app.log
+```
+
+## Follow along!
+
+```bash
+qurtail -F -n 50 app.log
+```
+
+`-n` is the number of existing lines to read when the file opens. The default is 10, like `tail`.
+Both `-f` and `-F` continue following when the file is truncated, replaced, or rotated.
+
+Leave off the follow flag when you want to compact a file once and exit:
+
+```bash
+qurtail app.log
+```
+
+For a particularly busy log, print one dot for every ten suppressed records:
+
+```bash
+qurtail -F --dot-every 10 app.log
+```
+
+Every suppressed record produces one dot by default. Qurtail buffers those dots into short runs
+before writing them, then closes the run with the exact repeat count and a newline when the pattern
+changes, 30 seconds pass, or monitoring stops. It doesn't redraw old terminal lines with
+backspaces or carriage returns, so captured output stays readable too.
+
+## Run a command
+
+If qurtail is launching the noisy command, use `run`:
+
+```bash
+qurtail run -- pytest -q
+```
+
+Everything after `--` is passed directly to the child command. There is no implicit shell in the
+middle interpreting pipes, substitutions, or redirects.
+
+Standard output and standard error are combined and sent through the same conservative reducer.
+Qurtail returns the child's success or failure status. If you interrupt qurtail, it interrupts and
+reaps the child process before exiting. A failed test run should still look like a failed test run;
+saving screen space is no excuse for losing the exit code.
+
+The same form works for container logs:
+
+```bash
+qurtail run -- docker logs -f api
+```
+
+```bash
+qurtail run -- kubectl logs -f deploy/api --timestamps
+```
+
+When another command already owns the pipeline, qurtail can read standard input:
+
+```bash
+producer 2>&1 | qurtail
+```
+
+With no filename and no `run` subcommand, it reads until standard input closes.
+
+Run `qurtail -h` for the complete command reference.
+
+## What counts as repetition?
+
+Qurtail uses bounded per-stream state to index patterns it has already printed. It recognizes a
+small, corpus-proven set of values that commonly change without changing the meaning of a log
+line:
+
+- timestamps
+- UUIDs
+- request, trace, and span IDs
+- standard JSON log metadata
+- stable container and service prefixes
+
+The matcher errs on the side of printing a line. It doesn't use a broad fuzzy-similarity score,
+since that is a good way to make an important number disappear. These two lines are different and
+both remain visible:
+
+```text
+replication lag is 1 second
+replication lag is 900 seconds
+```
+
+Unknown shapes, ambiguous values, and unfamiliar changing values also print in full. The same goes
+for malformed structured records and multiline content qurtail isn't sure how to join.
+
+Warning, error, and fatal transitions stay visible, along with HTTP status changes and changed
+structured error payloads. Same-level errors with different details get their own full record.
+Tracebacks, stack traces, and other multiline diagnostic blocks stay together. Repeated identical
+errors may be summarized after one complete example.
+
+Every suppressed record increments the count for its visible pattern. Suppressed records don't
+teach the matcher new patterns, so a hidden record cannot become the hidden example that makes some
+later line disappear.
+
+### Optional aggressive matching
+
+Conservative matching remains the default. When changing values still make repetitive output look
+unique, `--aggressive` also treats these hexadecimal, path, and long-integer values as noise.
+
+Keep in mind that sometimes ports, years, durations, byte counts, identifiers, and affected paths can all matter. Only use `--aggressive` when those values are noise.
+
+## Keep the raw output if you'll need it
+
+Qurtail is just a viewing helper to reduce noise. You may still want the followed stream captured.
+
+When qurtail runs the child command, use `--raw-log` to keep the raw text:
+
+```bash
+qurtail run --raw-log api.raw.log -- docker logs -f api
+```
+
+(The raw-log path must be new. To deliberately replace an existing log, add `--overwrite`.)
+
+For a pipe, keep the raw copy before the stream reaches qurtail:
+
+```bash
+docker logs -f api 2>&1 | tee api.raw.log | qurtail
+```
+
+Without `--raw-log`, qurtail doesn't create a transcript or keep a second copy.
+
+## What qurtail doesn't do
+
+Qurtail compacts a live local stream while it passes through. It doesn't store logs unless you ask.
+
+## Benchmarks and tests
+
+The benchmark suite includes regression fixtures, held-out monitoring episodes, and large-corpus
+runs. Installed-command smoke tests run on Linux, macOS, and Windows.
+
+See [`benchmarks/README.md`](benchmarks/README.md) for more. If you have good log data you want to share, please open an issue or pull request. The more diverse the corpus, the better qurtail can be updated to recognize repetition.
+
+## Agent skill
+
+The included `qurtail-fluency` skill makes qurtail the default for verbose tests, builds,
+installers, development servers, services, container and Kubernetes workloads, and followed logs.
+
+## Changelog
+
+### 1.0.0
+
+- Added opt-in aggressive matching for long integers, prefixed hexadecimal values, and absolute
+  paths.
+- Protected existing raw transcripts by default and added an explicit overwrite option.
+- Kept corpus-integrity verification byte-exact across Linux, macOS, and Windows.
+- Included the complete MIT license in source and built distributions.
+
+## License
+
+[MIT License](LICENSE.md)

qurtail-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qurtail"
+version = "1.0.0"
+description = "Follow logs while compacting conservative repeated patterns"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [
+  { name = "Mattie Casper" },
+]
+
+[project.urls]
+Repository = "https://github.com/Mattie/qurtail"
+Issues = "https://github.com/Mattie/qurtail/issues"
+
+[project.scripts]
+qurtail = "qurtail:main"
+
+[tool.setuptools]
+py-modules = ["qurtail"]

qurtail-1.0.0/qurtail.egg-info/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: qurtail
+Version: 1.0.0
+Summary: Follow logs while compacting conservative repeated patterns
+Author: Mattie Casper
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Mattie/qurtail
+Project-URL: Issues, https://github.com/Mattie/qurtail/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+# qurtail can Quell Unwanted Repetition
+
+Long-running logs have a bad habit of saying the same thing thousands of times with a new
+timestamp attached. That is tolerable when you're watching a terminal. It gets expensive and
+fairly useless when a coding agent has to read the whole thing.
+
+`qurtail` gives you or your agent a smaller view of the stream. It prints the first example of a repeated pattern, shows dots while more copies arrive, and closes the run with an exact count. Warnings, errors, status changes, unfamiliar numbers, and multiline diagnostics stay visible.
+
+```text
+> qurtail -F -n 50 app.log
+2026-08-08T12:00:00Z INFO refreshed cache request_id=715a
+........ [8 similar in 1s]
+2026-08-08T12:00:09Z ERROR cache refresh failed: connection refused
+..... [5 similar before stop]
+```
+
+A silent monitor is hard to distinguish from a stuck one. Qurtail provides the dots by default as a small sign of life, but you can change that with `--dot-every`.
+
+## Install it
+
+Qurtail requires Python 3.11 or newer. It has no runtime dependencies.
+
+
+To install from PyPI:
+```bash
+uv tool install qurtail
+# or
+pipx install qurtail
+```
+
+To install from GitHub:
+```bash
+git clone https://github.com/Mattie/qurtail.git
+cd qurtail
+uv tool install .
+```
+
+Or use `pipx` after cloning:
+
+```bash
+pipx install .
+```
+
+To run the repository once without installing it:
+
+```bash
+uvx --from . qurtail -F -n 50 app.log
+```
+
+## Follow along!
+
+```bash
+qurtail -F -n 50 app.log
+```
+
+`-n` is the number of existing lines to read when the file opens. The default is 10, like `tail`.
+Both `-f` and `-F` continue following when the file is truncated, replaced, or rotated.
+
+Leave off the follow flag when you want to compact a file once and exit:
+
+```bash
+qurtail app.log
+```
+
+For a particularly busy log, print one dot for every ten suppressed records:
+
+```bash
+qurtail -F --dot-every 10 app.log
+```
+
+Every suppressed record produces one dot by default. Qurtail buffers those dots into short runs
+before writing them, then closes the run with the exact repeat count and a newline when the pattern
+changes, 30 seconds pass, or monitoring stops. It doesn't redraw old terminal lines with
+backspaces or carriage returns, so captured output stays readable too.
+
+## Run a command
+
+If qurtail is launching the noisy command, use `run`:
+
+```bash
+qurtail run -- pytest -q
+```
+
+Everything after `--` is passed directly to the child command. There is no implicit shell in the
+middle interpreting pipes, substitutions, or redirects.
+
+Standard output and standard error are combined and sent through the same conservative reducer.
+Qurtail returns the child's success or failure status. If you interrupt qurtail, it interrupts and
+reaps the child process before exiting. A failed test run should still look like a failed test run;
+saving screen space is no excuse for losing the exit code.
+
+The same form works for container logs:
+
+```bash
+qurtail run -- docker logs -f api
+```
+
+```bash
+qurtail run -- kubectl logs -f deploy/api --timestamps
+```
+
+When another command already owns the pipeline, qurtail can read standard input:
+
+```bash
+producer 2>&1 | qurtail
+```
+
+With no filename and no `run` subcommand, it reads until standard input closes.
+
+Run `qurtail -h` for the complete command reference.
+
+## What counts as repetition?
+
+Qurtail uses bounded per-stream state to index patterns it has already printed. It recognizes a
+small, corpus-proven set of values that commonly change without changing the meaning of a log
+line:
+
+- timestamps
+- UUIDs
+- request, trace, and span IDs
+- standard JSON log metadata
+- stable container and service prefixes
+
+The matcher errs on the side of printing a line. It doesn't use a broad fuzzy-similarity score,
+since that is a good way to make an important number disappear. These two lines are different and
+both remain visible:
+
+```text
+replication lag is 1 second
+replication lag is 900 seconds
+```
+
+Unknown shapes, ambiguous values, and unfamiliar changing values also print in full. The same goes
+for malformed structured records and multiline content qurtail isn't sure how to join.
+
+Warning, error, and fatal transitions stay visible, along with HTTP status changes and changed
+structured error payloads. Same-level errors with different details get their own full record.
+Tracebacks, stack traces, and other multiline diagnostic blocks stay together. Repeated identical
+errors may be summarized after one complete example.
+
+Every suppressed record increments the count for its visible pattern. Suppressed records don't
+teach the matcher new patterns, so a hidden record cannot become the hidden example that makes some
+later line disappear.
+
+### Optional aggressive matching
+
+Conservative matching remains the default. When changing values still make repetitive output look
+unique, `--aggressive` also treats these hexadecimal, path, and long-integer values as noise.
+
+Keep in mind that sometimes ports, years, durations, byte counts, identifiers, and affected paths can all matter. Only use `--aggressive` when those values are noise.
+
+## Keep the raw output if you'll need it
+
+Qurtail is just a viewing helper to reduce noise. You may still want the followed stream captured.
+
+When qurtail runs the child command, use `--raw-log` to keep the raw text:
+
+```bash
+qurtail run --raw-log api.raw.log -- docker logs -f api
+```
+
+(The raw-log path must be new. To deliberately replace an existing log, add `--overwrite`.)
+
+For a pipe, keep the raw copy before the stream reaches qurtail:
+
+```bash
+docker logs -f api 2>&1 | tee api.raw.log | qurtail
+```
+
+Without `--raw-log`, qurtail doesn't create a transcript or keep a second copy.
+
+## What qurtail doesn't do
+
+Qurtail compacts a live local stream while it passes through. It doesn't store logs unless you ask.
+
+## Benchmarks and tests
+
+The benchmark suite includes regression fixtures, held-out monitoring episodes, and large-corpus
+runs. Installed-command smoke tests run on Linux, macOS, and Windows.
+
+See [`benchmarks/README.md`](benchmarks/README.md) for more. If you have good log data you want to share, please open an issue or pull request. The more diverse the corpus, the better qurtail can be updated to recognize repetition.
+
+## Agent skill
+
+The included `qurtail-fluency` skill makes qurtail the default for verbose tests, builds,
+installers, development servers, services, container and Kubernetes workloads, and followed logs.
+
+## Changelog
+
+### 1.0.0
+
+- Added opt-in aggressive matching for long integers, prefixed hexadecimal values, and absolute
+  paths.
+- Protected existing raw transcripts by default and added an explicit overwrite option.
+- Kept corpus-integrity verification byte-exact across Linux, macOS, and Windows.
+- Included the complete MIT license in source and built distributions.
+
+## License
+
+[MIT License](LICENSE.md)

qurtail-1.0.0/qurtail.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE.md
+README.md
+pyproject.toml
+qurtail.py
+setup.py
+qurtail.egg-info/PKG-INFO
+qurtail.egg-info/SOURCES.txt
+qurtail.egg-info/dependency_links.txt
+qurtail.egg-info/entry_points.txt
+qurtail.egg-info/top_level.txt
+tests/test_benchmarks.py
+tests/test_codex_workloads.py
+tests/test_large_corpus.py
+tests/test_performance.py
+tests/test_qurtail.py

qurtail-1.0.0/qurtail.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qurtail-1.0.0/qurtail.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qurtail = qurtail:main

qurtail-1.0.0/qurtail.egg-info/top_level.txt

@@ -0,0 +1 @@
+qurtail