jlogtail
A Rust command-line tool and Python module that read the end of large JSON Lines transcripts without loading the whole file.
The demo uses synthetic transcript rows. It shows field selection and filtering, not benchmark data.
Install
cargo install --path .
pipx install jlogtail
# or: uv tool install jlogtail
The wheel installs the jlogtail command and the importable jlogtail PyO3 module. Use Cargo to install the standalone Rust CLI from this directory. Python 3.9+ is required; source builds also require Rust.
Quick start
jlogtail ~/.claude/projects/PROJECT/session.jsonl --lines 20
jlogtail ~/.codex/sessions/SESSION.jsonl --bytes 65536
jlogtail transcript.jsonl --filter payload.role=assistant --fields timestamp,payload.role
jlogtail transcript.jsonl --follow
Claude Code, Codex, and Pi transcripts use the same JSONL commands. The CLI outputs original rows by default. --fields emits a compact object with selected dotted paths. --filter PATH=VALUE compares JSON values; unquoted non-JSON values are strings. A byte window skips a partial first record but keeps it when the window starts at a line boundary. Follow reads each appended byte once, keeps an incomplete row in memory, and emits it when the newline arrives.
$ jlogtail docs/demo/agents.jsonl --lines 2 --fields role,text
{"role":"assistant","text":"Checkpoint 42 finished."}
{"role":"assistant","text":"The next run is queued."}
How it reads
Why
tail -n 20 file.jsonl | jq . is useful for full-file pipelines and richer JSON queries, but it reads from the start to find the last rows. This tool seeks backward to the requested records, then reads only that suffix. It is for large transcripts and repeated polling.
Measurements
On M5 Pro, macOS arm64, hyperfine ran 3 warmups and 10 measured runs per command against one 2.18 GB temporary copy. The read-only 272.9 MB source transcript was repeated eight times. Mean wall times were 5.0 ms for jlogtail, 66.5 ms for tail | jq, and 1395.6 ms for Python's full read. See the summary, raw output, and raw measurements. Results describe this copy and host only.
Reference
| Option | Meaning |
|---|---|
--lines N, -n N |
Read the last N complete records; default 10 |
--bytes N, -c N |
Read N trailing bytes and drop a partial first record unless the window starts at a line boundary |
--follow, -f |
Emit complete appended records; restart from byte 0 after replacement or truncation |
--filter PATH=VALUE |
Keep rows whose dotted key path equals the JSON value |
--fields PATH,... |
Emit only the selected dotted paths as a compact object |
--poll-ms N |
Follow poll interval; default 250 ms |
--keep-partial-first |
Keep the first partial row in a byte window |
The Python module provides jlogtail.tail(path, lines=20) for raw complete rows; use byte_window=N to choose a suffix by bytes. jlogtail.select_native(path) returns a metadata dictionary and oldest-to-newest Codex message objects. lib/native-history-tail.py preserves feno-handoff's existing one-path command and metadata output.
Limits
The benchmark and demo ran on macOS arm64. Linux and Windows builds have not been exercised. Follow compares platform file IDs and resets when it observes a shorter file. The benchmark ran on macOS arm64; Linux and Windows follow behavior has not been exercised. A filter requires valid JSON. A follow poll waits for the newline that completes each row.
License
MIT. See LICENSE.
Metadata
Release files for jlogtail 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jlogtail-0.1.1.tar.gz | 159.5 kB | Without provenance | Details for jlogtail-0.1.1.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| jlogtail-0.1.1-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for jlogtail-0.1.1-cp39-abi3-win_amd64.whl |
| jlogtail-0.1.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details for jlogtail-0.1.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| jlogtail-0.1.1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details for jlogtail-0.1.1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| jlogtail-0.1.1-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for jlogtail-0.1.1-cp39-abi3-macosx_11_0_arm64.whl |
| jlogtail-0.1.1-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for jlogtail-0.1.1-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 1.6 MB
Release files / jlogtail-0.1.1.tar.gz
| Download URL | jlogtail-0.1.1.tar.gz |
|---|---|
| Size | 159.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc940c5c0eafd6f2e7c48b3c1e627aea69e4f2b7dd85834eeb1f493e0eb9b52e
|
|
BLAKE2b-256 checksum How to use checksums |
812c7f017e635ea0b360a6095d97083edc254751bfb9aa900a81f4a98d757491
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / jlogtail-0.1.1-cp39-abi3-win_amd64.whl
| Download URL | jlogtail-0.1.1-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 191.2 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
6775efe7f2f2862dfdf62a40fb0cdc7bc0f7c7e75751b8e8b7e8effc669a511b
|
|
BLAKE2b-256 checksum How to use checksums |
7e0afc179fc23e158cc278ad346a28c616aa191b72da0788e888d315700f22e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / jlogtail-0.1.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | jlogtail-0.1.1-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 329.7 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
90262e90db48de3ccc5b149b3abb63787a03a1c1ab4988ee9dc244fb15eab928
|
|
BLAKE2b-256 checksum How to use checksums |
354b32824ec2922e037b1fa25c6015b1a65a30b2735f72aef0f8751df0728f50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / jlogtail-0.1.1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | jlogtail-0.1.1-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 314.9 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
9de650fc4b3c746c685f9012d412ec4e264c59b6ee9ddaaa9ccdfab1d780edf3
|
|
BLAKE2b-256 checksum How to use checksums |
8205558e80ba2b7a14f05a95da7de0989062ede86894de46fe797ee821599109
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / jlogtail-0.1.1-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | jlogtail-0.1.1-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 290.2 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f3f9e9df253113a7503a969cb6237f7b4109b6cd49559b4c7da10291522d61f3
|
|
BLAKE2b-256 checksum How to use checksums |
62dc0a60f5f50432064d1f0aefa6906d932164c80caa5d24f4f0e88243abc3b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Release files / jlogtail-0.1.1-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | jlogtail-0.1.1-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 296.1 kB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
81ee46062c789a4fb82eb89f6002f6ade5182ce11bb752721142256beda3c051
|
|
BLAKE2b-256 checksum How to use checksums |
4fd0028a029c0d5c6d88b8502dd428ecc38c937791579293b5da7f3da500542f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.8
|
Security for jlogtail 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.