filens

An Agent CLI. A pure frontend viewer for complex file formats.

Read, search, OCR, convert and preview local files. Files stay on your device.

English · 简体中文 · MIT

▶ Watch the 30-second walkthrough · Animated preview · Format coverage and limits

	Agent CLI	Pure frontend previews
Use it for	Give Agents source text, search results, OCR and cited evidence; open a browser preview.	Preview Office, iWork, PDF, CAD / 3D, RAW, panoramas, archives and more in your app.
Approximate size	Lite: 7.68–8.04 MiB installed · Full: 31.10–36.74 MiB installed, including OCR runtime and models.	A few KB to hundreds of KB per compressed chunk; shared dependencies, workers and WASM add to the total. An all-in-one JS file is also available.
Start here	Install and use the CLI	Preview and integrate

The native executable is 1.78–2.15 MiB. Lite and Full sizes include the launcher, native executable and document WASM; Full also includes OCR runtime and models. Sizes vary by platform and exclude Node.js, npm caches and optional preview assets (1 MiB = 1,048,576 bytes). Frontend chunk figures describe compressed build artifacts. Preview 0.1.4 uses truck for STEP and excludes OCCT: 2.44 MB Brotli across split runtime files, or 2.84 MB Brotli / 3.79 MB gzip / 12.70 MB raw as one JS file, including Vue, styles, workers and WASM. Media uses browser codecs with a small HEIC/HEIF decoder fallback; full FFmpeg is excluded. CLI measurements · Standalone measurements.

Agent CLI

Read PDFs, Office documents, spreadsheets, scans and images locally. Search directories and nested archives; extract key original passages; find duplicate files and similar images. Outputs include text, JSON, Markdown, HTML, YAML, XML, CSV and TSV, with available page coordinates and document structure. Paraphrasing, translation and question answering belong to the calling Agent.

Ask your Agent to install it:

Install filens for me. Find skills/filens/SKILL.md at https://github.com/IceWhaleTech/filens and follow it to set up the CLI and skill.

Skill guide · Or install the CLI yourself:

# Full: native RapidOCR and Chinese/English models; no Python
npm install -g filens-cli
filens 'read "report.pdf" as json'
filens 'search "./documents" for "budget risk" as json'
filens summarize report.pdf --query 'budget risk' --json
filens convert report.doc report.docx

# Lite: add OCR later with filens setup-ocr
npx --yes filens-cli-lite capacity --json

Browser preview from the CLI: filens preview report.pdf opens the shared frontend viewer. The first use installs the separate filens-preview package; filens setup-preview prepares it in advance. --no-open --json prints a local URL and keeps the server running until stopped. Preview 0.1.4 includes both builds (about 7.0 MB download / 24.34 MB installed), measured separately from CLI sizes. CLI 0.4.2 downloads this version automatically; earlier CLI releases retain their pinned preview version. See package measurements. Preview setup and limits.

CLI sizes, capabilities and further examples

CLI executable 2.15 MiB · Lite 8.04 MiB · Full 31.25 MiB · MIT
_{v0.4.2 · macOS arm64 · Lite/Full installed packages, Full includes OCR models; all platform sizes}

• Installation, protocol and packaging · Agent skill
• Output formats and layouts · 68 observed examples and limits
• Search, nested archives and model-free key excerpts
• Duplicates and similar images · Windows setup and validation status
• Search coverage, retrieval benchmarks and startup costs

The CLI uses Rust and the same frontend conversion core. Full bundles RapidOCR NCNN (max side 960, two OpenMP threads); Lite adds it with filens setup-ocr. Inspect capacity for the installed build's operations and conversion pairs. Natural-language requests recognize a bounded set of intents; page selection and field-specific questions are not implemented. Windows/Linux native execution remains pending validation.

macOS OCR comparison: Apple Vision is faster on the tested warm image calls, but loses tiny text and can be less accurate on blurred input; fresh-process latency is also higher. It cannot yet replace RapidOCR across this project's requirements. Measurements, capability gaps and reproduction.

Pure frontend previews

Complex formats, processed in the browser with no upload or conversion server. Browse Keynote slides, Pages pages and Numbers sheets; read Office and PDF documents; inspect CAD and 3D models; view RAW photos and 360° photos or video.

Single file or split modules

npm install filens-preview

The same API is available in both builds. Vue, styles and the conversion engines are included; your app needs no Vue installation.

<div id="preview" style="height: 80vh"></div>
<script type="module">
  // Split build: deploy the entire split/ directory; engines load as needed.
  import { createPreview } from 'filens-preview';
  // Single-file alternative: deploy all-in-one/filens.js (styles, WASM and workers included).
  // import { createPreview } from 'filens-preview/all-in-one';

  const viewer = createPreview('#preview', { src: './report.pdf', name: 'report.pdf' });
  // viewer.update({ src: anotherFile, name: anotherFile.name });
  // viewer.destroy();
</script>

Use a bundler for npm imports, or deploy the package runtime directory and import its filens.js over HTTP(S). For a Vue app, use the shared Preview component; for direct JavaScript integration and CLI previews, see the standalone guide. Single-file packaging trades a larger initial download for simpler deployment; it has the same format limits as the split build.

Files	Preview	Main limits
PPTX, Keynote / Pages / Numbers	Slide, page and worksheet canvases.	Fidelity varies by layout, fonts and objects.
DOCX, XLSX / CSV, PDF	Documents, sheets and paged PDFs.	Read-only; advanced styling may differ.
DOC / XLS / PPT, WPS / ET / DPS	Local WASM conversion for preview.	Preview-focused; macros are stripped.
DXF, STEP / STP, mesh models	Pan drawings and orbit 3D geometry.	STEP omits source colors, names and assembly trees.
RAW, common images and icons	Embedded JPEG first, lightweight RAW development as fallback.	Camera coverage and image quality vary.
360° photos and video	Interactive viewing and supported camera-original stitching.	Stitching is experimental; metadata, sidecars and browser codecs matter.
Archives, ebooks, code, mind maps and diagrams	Browse entries, chapters, source and node relationships.	Each format supports a documented subset.

Detailed bundle sizes and loading costs

Module / core	Raw	gzip	Brotli
Conversion core WASM	1123.1 KiB	497.8 KiB	395.8 KiB
Image / RAW core WASM	1099.9 KiB	298.4 KiB	216.3 KiB
Media / panorama preview	229.0 KiB	67.1 KiB	57.2 KiB
truck STEP WASM (default)	925.5 KiB	326.4 KiB	255.0 KiB

Document, image / RAW, and STEP WASM modules load independently on demand. STEP uses truck; OCCT is excluded from the build. Media preview and image conversion are measured separately. JS rows include their CSS; shared dependencies and workers are listed separately.

All modules and initial loading cost

Module / core	Raw	gzip	Brotli
HEIC / HEIF decoder WASM	1429.2 KiB	474.4 KiB	347.4 KiB
Demo entry	212.9 KiB	61.0 KiB	51.3 KiB
Agent CLI demo UI	28.8 KiB	11.4 KiB	9.3 KiB
Shared vendor dependencies	1329.1 KiB	373.3 KiB	308.2 KiB
PPTX / core runtime	336.6 KiB	93.0 KiB	78.9 KiB
Vue preview host	78.7 KiB	18.6 KiB	16.5 KiB
DOCX / XLSX / PDF	42.8 KiB	12.9 KiB	11.6 KiB
On-demand PDF engine	435.2 KiB	128.1 KiB	106.9 KiB
iWork preview	35.4 KiB	11.0 KiB	9.8 KiB
CAD / mind maps / diagrams	92.1 KiB	25.7 KiB	22.1 KiB
3D preview	132.9 KiB	37.5 KiB	32.6 KiB
Media decoder loader	119.5 KiB	42.8 KiB	37.4 KiB
Archive preview	25.0 KiB	8.0 KiB	7.1 KiB
Text / ebooks	28.6 KiB	9.7 KiB	8.6 KiB
iWork worker	894.1 KiB	186.7 KiB	156.2 KiB
PDF worker	1053.3 KiB	291.1 KiB	233.1 KiB
truck STEP loader	2.8 KiB	1.4 KiB	1.2 KiB

Entry, preloaded JS, and CSS total 495.6 KiB Brotli (2107.6 KiB raw / 594.3 KiB gzip), plus images, video, and samples. Modules share dependencies; these rows are not standalone per-format download totals.

Measured from the demo build. Compression columns describe artifacts; actual transfer depends on hosting. Full report and reproduction.

The table above is the recorded demo-build snapshot. The new standalone builds have their own complete measurements, including embedded dependencies. Individual chunks are not independent per-format download totals.

Frontend project comparisons

Frontend project	iWork	360° photos / video	RAW preview	Native PPTX	CAD / 3D
filens	✅ All three	✅	◐	✅	✅
SheetJS CE	◐ Numbers	—	—	—	—
Photo Sphere Viewer	—	✅	—	—	—
LibRaw-Wasm	—	—	✅	—	—
vue-office	—	—	—	✅	—
PPTist	—	—	—	✅	—
Online 3D Viewer	—	—	—	—	✅

_{✅ Available path · ◐ Partial or conditional support · — No built-in path documented. Format coverage and limits.}

iWork, panoramas, RAW, Office, and CAD / 3D in one browser-local workspace. The projects above specialize in different areas; filens brings these previews together.

Comparison notes and support boundaries

• Entries follow public documentation and browser-local processing paths, rather than overall project rankings. Support and fidelity vary by file.
• iWork / PPTX: filens previews Keynote, Pages, and Numbers natively. SheetJS extracts Numbers table data and needs an application UI. PPTist imports PPTX into its presentation model; vue-office's PPTX core is not open source.
• Panoramas: both filens and Photo Sphere Viewer display photos and video. filens also handles supported X5 INSP originals, Insta360 / DJI calibration and distortion, original-track synchronization, and calibrated DNG stitching. Camera-original stitching is experimental and depends on metadata, companion files, and browser codecs. PSV's generic dual-fisheye adapter does not parse X5 calibration.
• RAW: filens prioritizes embedded JPEGs, then lightweight sensor development. LibRaw-Wasm offers full / half-size decoding and development through an API that needs an application UI. These paths have different image-quality goals.
• CAD / 3D: filens covers DXF, STEP, and mesh previews. Online 3D Viewer specializes in model viewing, inspection, and export, including STEP / IGES / IFC. filens STEP previews retain geometry and instance placement, but omit source colors, names, and the assembly tree.

Run the demo locally

Requires Node.js 20+ and Rust via rustup. The repository pins the Rust compiler and WASI target.

npm ci
npm run build:wasm
npm run dev --workspace @filens/demo

Open the local demo, choose a sample or drop in a file. For hosting, see the Vercel guide.

Install on ZimaOS

Install FiLens from the official Mod Store. In the ZimaOS terminal or over SSH, run:

sudo zpkg install filens

This installs the native CLI and shared WASM engines for Linux x64/arm64, with no Node.js dependency. Run filens capacity --json, then filens read report.pdf --json. OCR reuses Photos' installed NCNN v7 runtime and RapidOCR models. If they are absent or incompatible, filens setup-ocr installs a compatible private copy; document reading and conversion work without OCR.

If the module is not found, run sudo zpkg update to refresh the store index, then retry. See the ZimaOS packaging guide for building, publishing and updating the package.

Performance and documentation

Show SOTA benchmark results

Measured task	filens	Current peer	Speedup*
11.1 MB, 13-slide PPTX parse	28.5 ms	pptx-preview 1.0.7: 56.6 ms	1.99×
11.1 MB, 13-slide PPTX first preview	48.8 ms	pptx-preview 1.0.7: 71.8 ms	1.47×
3840×1920 panorama JPEG preview	154.9 ms	Photo Sphere Viewer 5.15.1: 205.2 ms	1.32×
X5 INSP preview, input/modules/WASM ready (Oct 27)	354.5 ms	Photo Sphere Viewer 5.15.1 dual fisheye: 383.0 ms	1.08×
NEF without embedded JPEG → preview canvas	152.7 ms	LibRaw-Wasm 1.6.0 half-size: 326.7 ms	2.14×
DNG without embedded JPEG → preview canvas	167.7 ms	LibRaw-Wasm 1.6.0 fast half-size: 314.4 ms	1.87×
STEP truck geometry import: cube (Nov 1)	11.9 ms	occt-import-js 0.0.23: 62.0 ms	5.21×
STEP truck geometry import: as1_pe_203 (Nov 1)	61.2 ms	occt-import-js 0.0.23: 195.0 ms	3.19×
STEP truck geometry import: as1-oc-214 (Nov 1)	224.2 ms	occt-import-js 0.0.23: 243.8 ms	1.09×
XLSX data read (80,000 cells)	42.3 ms	SheetJS CE 0.20.3: 109.6 ms	2.59×
XLS → XLSX preview conversion (6 sheets)	12.3 ms	x2t WASM v9.3.2+3: 49.1 ms	4.00×
20,000×8 numeric CSV → XLSX	137.6 ms	x2t WASM v9.3.2+3: 198.8 ms	1.44×

Stable leads against specialized frontend libraries. At least seven runs per configuration, with 21 for the X5 original; sensor development and preview drawing on five RAW inputs without embedded JPEGs are 1.11–2.14× faster than the measured LibRaw paths.

_{* Limited to this machine, measured inputs and listed peers, supported by paired bootstrap 95% intervals; downloads and library cold loading excluded. Apple M4 Pro / Chromium 147; panoramas use SwiftShader software rendering. On the X5 original, PSV's generic dual-fisheye projection visibly repeats scene content across hard seams; filens has lighter, localized ghosting. The speed label covers readable previews of this original. RAW measures development and drawing to a common canvas with different intermediate sizes; STEP uses the current truck reader: all six tested files lead after lossless binary mesh transport; as1-oc-214 takes 224.2 vs 243.8 ms. Meshes differ and pass an approximate geometry screen; this excludes scene construction and rendering; XLSX compares data reading; XLS compares the main displayed content in the same viewer. Full results, scope and reproduction.}

Measurement scope

_{RAW inputs have embedded JPEGs removed and unchanged sensor data. Both LibRaw half-size configurations draw to the same 1280×800 canvas; intermediate resolution, tone and crop differ slightly. Timing includes development, output decode/transfer and drawing. The full Numbers model and several small PPTX first previews still have room to improve; see the full results and preview comparisons.}

Looking for…	Start here
Standalone single-file / split builds and CLI preview	Preview guide
Vue integration	Vue components
Supported formats	Support matrix
Architecture and WASM boundaries	Project overview
Frontend benchmarks and raw data	Performance comparison
macOS native OCR vs RapidOCR	Measured comparison
CLI and backend integration	Agent CLI · Go + wazero host

Try your files and report a reproducible issue. Roadmap · MIT license · Third-party notices.

_{Preview captures come from filens. Photos and demo recordings retain their original licenses; see visual sources and credits. iWork research: dunhamsteve/iwork; CAD lineage: orcastor/cad2x-converter.}

Star History