A native desktop tool for browsing and querying large JSON files — drag in a file (or paste JSON directly), write a jq compatible query, and see the result as a scrollable tree. Built in Rust with egui/eframe.
This project — the code, the architecture docs, and the build tooling — was
built by Claude (Anthropic's AI), working from a series
of prompts by the repo owner. It's as much an experiment in AI-driven
software development as it is a JSON tool. The architecture proposal and
decision docs capture the reasoning behind the design
choices along the way — open them locally in a browser to read them rendered
(GitHub shows .html
files as source, not as pages).
Phase 1 (MVP) is implemented: full in-memory parsing, jq-compatible queries via an embedded jaq, and a virtualized-tree GUI for both the source document and query results. It's solid for small-to-medium files.
Multi-gigabyte files need Phase 2 (a memory-mapped, lazily-resolved index), which isn't built yet. See docs/decisions.html for the full roadmap and the reasoning behind what's built vs. deferred.
Drag-and-drop doesn't work on native Wayland. This is a gap in(the windowing librarywinit
eframe
uses), which only implements OS-level file drop events on Windows, macOS, and X11 —rust-windowing/winit#1881tracks it upstream.Open File… and pasting JSON directly both work fine everywhere. As a workaround, run under XWayland instead of native Wayland (ifDISPLAY
is set, XWayland is available) and drag-and-drop starts working:
WAYLAND_DISPLAY= cargo run --release -p jsonquery_gui
Open large-ish files fast— memory-mapped, no upfront full-file copy.** jq-compatible queries**— a real jq implementation (jaq) embedded directly, not a reinvented query language.** Streamed results**— results are pushed to the UI as jaq produces them, sofirst(...)
/limit(...)
genuinely stop early instead of running to completion in the background.Exact number round-tripping— big integers (snowflake IDs, Postgres bigints) survive a query byte-for-byte instead of quietly rounding through anf64
.NDJSON support— a file with one JSON value per line is treated as a single queryable document, no separate "format" to pick.** Cancellable queries**— start a new query and the previous one is aborted, not queued behind it.** Drag-and-drop, file picker, or paste**— drop a file anywhere in the window, use** Open File…, or just paste JSON into the text area and it loads immediately. Tree or raw text results**— toggle the results panel between the virtualized tree and plain pretty-printed text you can select and copy with the mouse.Light and dark themes— switchable from the toolbar.
Prebuilt Linux and Windows binaries can be produced with the scripts in build/ — see
Buildingbelow. (No binary releases are published yet; build from source in the meantime.)
Requires a Rust toolchain (stable).
git clone <this repository's URL>
cd jsonquery
cargo run --release -p jsonquery_gui
- Get JSON in: drag a file onto the window, use Open File…, or paste JSON straight into the text area on the left — it loads as soon as you paste, no extra step. - Write a query in the bar at the top — plain jq syntax, e.g.:
.users[] | select(.active) | {name, roles}
- Press
Run(or
Ctrl+Enter
). Results stream into the right-hand panel. Switch it betweenTree(virtualized, expand/collapse) and** Text**(plain, selectable/copyable pretty-printed JSON) with the toggle above it.
Native release build for the current platform:
cargo build --release -p jsonquery_gui
Cross-platform packaged builds live in build/, output to
dist/
:
build/linux.sh # native release build -> .tar.gz
build/appimage.sh # native release build -> self-integrating .AppImage
build/windows.sh # cross-compiled via `cross`/Docker -> .zip
build/all.sh # all three, plus a listing of dist/
build/windows.sh
needs a working Docker daemon — it cross-compiles inside a
container that already has the mingw-w64 toolchain, so nothing is installed
on the host. build/appimage.sh
downloads appimagetool
on first use
(cached in build/
) and needs FUSE to run it.
On an actual Windows machine, skip the cross-compile and build natively instead:
build\windows.bat # native release build -> .zip
Same output layout as the other scripts (dist\jsonquery_gui-<version>-windows-x86_64.zip
). Just needs a Rust toolchain and PowerShell (bundled since Windows 10 / Server 2016) to create the zip.
The AppImage is desktop-pinnable out of the box: on first launch it registers
a .desktop
entry and icon under ~/.local/share
(no appimaged
/
AppImageLauncher required), and the window's app ID matches
StartupWMClass
in that entry, so window managers correctly associate the running window with the launcher icon — right-click it in the taskbar/dock and "Pin" works as expected.
cargo test --workspace # unit tests (core parsing/tree logic, query engine)
cargo clippy --workspace --all-targets
The workspace is split into three crates so the non-GUI logic can be tested and benchmarked without pulling in a GUI toolkit:
— file ingest (mmap + parse) and the virtualized-tree data layer.crates/core
— the embedded jaq query engine and itscrates/query
serde_json::Value ⇄ jaq_json::Val
conversion.— the eframe/egui application itself.crates/app
scripts/gen_test_data.py generates a large synthetic JSON (or NDJSON) file for exercising the app — nested objects, unicode, and 19-digit integer ids that exceed
f64
's exact-integer range, to exercise the number round-tripping:
scripts/gen_test_data.py # ~200k records to test-data/large.json
scripts/gen_test_data.py --target-size 1GB -o test-data/big.json
scripts/gen_test_data.py --format ndjson -n 1000000 -o test-data/events.ndjson
Each run also prints a handful of jq queries worth trying against the file it
just generated (filtering, nested-field access, aggregation with
group_by
, and one that highlights the exact-integer round-tripping) —
see SAMPLE_QUERIES
in the script, kept next to the record shape it describes so the two can't drift apart.
The design — pipeline, indexing strategy, concurrency model, crate layout — is written up in docs/:
— problem statement, goals, high-level shape.docs/index.html
— the full system design.docs/architecture.html
— the decisions that shaped the build, open risks, and the roadmap.docs/decisions.html
(Open these locally in a browser — GitHub renders .html
files as source, not as pages.)