▶ 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.
Supported formats (by extension)	334.	397, including direct previews and previews after local WASM conversion.
Approximate size	Lite: 7.50–7.87 MiB installed · Full: 30.93–36.56 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.80–2.18 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.3.2 main runtimes: 2.67 MB Brotli summed across split files, or 3.02 MB Brotli / 3.34 MB gzip / 8.05 MB raw for the all-in-one JS. Optional archive WASM and worker add 0.28 MB Brotli / 0.35 MB gzip / 0.88 MB raw to either build. Main runtimes include Vue, styles, document/image/STEP WASM and their workers. Media uses browser codecs with a small HEIC/HEIF decoder fallback. CLI measurements · Standalone measurements.

Agent CLI

Supports 334 file formats (counted by extension). 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. Check filens capacity --json for your installation's capabilities; extraction fidelity varies by format. 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

Offline browser preview (CLI 0.5.2): filens preview report.pdf creates a self-contained HTML with the source file, preview engine and licenses, opens it locally and exits. No server or file upload is needed. The first preview installs filens-preview@0.3.2; run filens setup-preview in advance for offline use. The frontend package includes both builds and is measured separately: package sizes.

# Export a portable offline preview; existing files are never overwritten
filens preview report.pdf --output report-preview.html --no-open
# Return the generated file URL and path as JSON
filens preview report.pdf --no-open --json
# Browser compatibility mode: loopback HTTP server, Ctrl-C to stop
filens preview report.pdf --mode serve

The HTML checks browser capabilities and blocks external resource requests. It contains a copy of the original file; temporary HTML files remain after exit. Safari/WebKit iWork previews require HTTP compatibility mode. Preview setup and limits · Browser validation.

ZimaOS ModStore: install with sudo zpkg install filens. To upgrade, run sudo zpkg update and sudo zpkg upgrade filens. ModStore 0.5.1 includes the offline HTML preview engine for Linux x64/arm64 and always skips browser launching. Download or copy the generated HTML to your computer; --json returns its path on ZimaOS. Node.js and npm are not required. Install, export previews and configure OCR.

CLI sizes, capabilities and further examples

CLI executable 2.18 MiB · Lite 7.87 MiB · Full 31.09 MiB · MIT
_{v0.5.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

DeepSeek Harness: CLI tools and sidebar preview plugin, installed together and enabled independently. Tested with DSH Desktop 0.2.1-rc.5 and Web 0.2.2-alpha.3. Install with dsh plugin --profile desktop add dsh-filens@0.1.0.

Preview 397 file formats in the browser with no upload or conversion server. Counted by extension, including direct previews and previews after local WASM conversion. 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. See the support matrix for coverage and limits by format.

Single file or split modules

npm install filens-preview

iOS / Android: source SDKs are available as a local Swift Package and an Android Library, sharing the offline frontend and WASM runtime. See the mobile SDK integration guide and runtime, npm and SDK sizes.

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 (Office detection)	894.8 KiB	403.3 KiB	327.6 KiB
Image / RAW core WASM	1099.9 KiB	298.4 KiB	216.3 KiB
Media / panorama preview	230.0 KiB	67.1 KiB	57.3 KiB
truck STEP WASM	925.5 KiB	326.4 KiB	255.0 KiB

Document, image / RAW, and STEP WASM modules load independently on demand. 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
Office decryption WASM (optional)	370.2 KiB	160.1 KiB	127.4 KiB
HEIC / HEIF decoder WASM	1429.2 KiB	474.4 KiB	347.4 KiB
Demo entry	213.6 KiB	61.3 KiB	51.6 KiB
Agent CLI demo UI	28.8 KiB	11.4 KiB	9.3 KiB
Shared vendor dependencies	1407.1 KiB	406.1 KiB	339.8 KiB
PPTX / core runtime	353.8 KiB	98.8 KiB	83.6 KiB
Vue preview host	173.6 KiB	49.2 KiB	38.9 KiB
DOCX / XLSX / PDF	43.7 KiB	13.2 KiB	11.8 KiB
On-demand PDF engine	435.2 KiB	128.1 KiB	106.9 KiB
iWork preview	36.6 KiB	11.2 KiB	10.0 KiB
CAD / mind maps / diagrams	92.1 KiB	25.7 KiB	22.0 KiB
3D preview	132.8 KiB	37.5 KiB	32.6 KiB
Media decoder loader	125.6 KiB	46.1 KiB	40.1 KiB
Archive preview	32.2 KiB	10.4 KiB	9.2 KiB
RAR / 7z extraction WASM (optional)	810.2 KiB	322.5 KiB	253.4 KiB
Archive worker (optional)	51.2 KiB	18.1 KiB	16.2 KiB
Text / ebooks	29.8 KiB	9.9 KiB	8.8 KiB
iWork worker	883.5 KiB	183.0 KiB	152.7 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 532.2 KiB Brotli (2204.5 KiB raw / 633.2 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 format package audit records dependency sharing, worker packaging and measured savings for applications combining the npm libraries.

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.

On ZimaOS, filens preview report.pdf --output report-preview.html --json exports an HTML without launching a browser. Download or copy it to your computer to open it. HTTP compatibility mode requires an SSH tunnel to the loopback port.

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
Browser media without a conversion server	Integration, limits and validation
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