DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

orca-zhang /

orca-zhang/filens

Topic repository only

📄 Office / PDF / iWork / CAD / 3D / RAW / 360° 🔒 Browser-local preview & conversion 🤖 Agent CLI with OCR, structured text & layout extraction ⚡ Rust + WebAssembly 🧩 Vue 3 integration. Open-source, local-first. Your files, your device.

★ 1 Stars0 Forks1 IssuesN/A Community rating0 Confirmed installs
View on GitHubProject homepage
READMESource: main@9f0e3824
filens logo

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

Actual CLI results: OCR geometry, key excerpts, nested archive search and reading, duplicate files, similar images, CSV-to-XLSX conversion, offline HTML workbook and STEP previews

Eight actual previews: Office, PDF, iWork, CAD, 3D and panoramas

Latest release: v0.6.6 · CLI 0.5.6 · preview 0.3.6 · mobile SDKs 0.1.6 · DSH 0.1.9.

▶ 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) 349. 450, including direct previews and previews after local WASM conversion.
Approximate size Lite: 6.90–7.17 MiB (<10 MB) · Full: 31.26–33.80 MiB offline downloads; Full includes preview assets, OCR runtime and models. Lite downloads preview assets separately. 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 0.92–2.20 MiB. The CLI sizes above measure complete v0.6.6 offline archive downloads. Full includes preview 0.3.6, OCR runtime and models; Lite retains reading, search and conversion with OCR/preview assets optional. Lite archives must stay strictly below 10,000,000 bytes (10 MB); packaging fails at or above that limit. See archive and extracted sizes (1 MiB = 1,048,576 bytes). npm CLI 0.5.6 component installations remain 8.00–9.27 MiB Lite / 31.43–37.06 MiB Full, excluding Node.js, caches and preview assets. Frontend chunk figures describe compressed build artifacts. Preview 0.3.6 source-build main runtimes: 4.16 MB Brotli summed across split files, or 3.40 MB Brotli / 3.54 MB gzip / 6.69 MB raw for the supplied precompressed all-in-one JS. Optional archive WASM and worker add 0.36 MB Brotli / 0.46 MB gzip / 1.17 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.

Verified November 6, 2026: CLI 349 extensions; preview 450 source-file extensions (451 route entries including internal cad-json). Versions, counts and complete extension list.

Agent CLI

Supports 349 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.

Installation and use

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 · For manual installation, download your platform’s offline bundle from the latest Release and extract the entire archive. Full includes offline preview assets, OCR and models. Lite keeps OCR and preview assets optional. Both run without Node.js or npm.

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

filens inspect unknown-file --json
filens capacity --json

filens inspect FILE --json identifies the actual format from bounded content reads, reports MIME/evidence and extension mismatches, and keeps ambiguous inputs explicit. It uses no OCR and does not validate the entire file.

Offline browser previews

CLI 0.5.6: 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 v0.6.6 Full bundles include preview 0.3.6. With Lite, download and extract the all-in-one runtime ZIP, then pass --assets /path/to/filens-preview-0.3.6-all-in-one or set FILENS_PREVIEW_DIR. Copying its contents into preview/ beside the executable also enables automatic discovery. npm CLI 0.5.6 retains preview 0.3.4; DSH 0.1.9 embeds preview 0.3.6; npm installations can prepare assets with filens setup-preview. 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

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.20 MiB · Lite 7.17 MiB · Full 31.91 MiB · MIT
v0.6.6 offline downloads · macOS arm64 · CLI 0.5.6; Full includes preview 0.3.6 and OCR models; Lite adds preview assets separately; 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; use explicit --pages / --slides for selection. 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

Preview 450 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.

DeepSeek Harness

Faster first previews than DSH built in: PPTX 13.56× · DOCX 16.46× · PDF 1.73×.

Typical file DSH built in · first open FiLens 0.1.3 · first open Speedup
PPTX presentation 1,830 ms 135 ms 13.56×
DOCX document 1,827 ms 111 ms 16.46×
PDF document 329 ms 190 ms 1.73×

Recorded November 5, 2026 on Apple M4 Pro/macOS and DSH Desktop 0.2.1-rc.5: nine paired rounds per format, medians through render readiness, excluding application startup. Office and PDF use separate runs; these are retained FiLens 0.1.3 measurements. PDF cached opens also improve from 110 to 77 ms (1.43×). Office samples and method · PDF samples and method.

Install dsh-filens@0.1.9 in Plugins → Add plugin → Install → Enable now for native sidebar previews of 450 formats, plus local reading, OCR, search and conversion. Setup and usage · 3D / 360° gallery · Measured comparisons.

DSH 0.1.9: 5.81 MiB download / 17.58 MiB unpacked, including the built-in workspace. CLI/OCR dependencies and DSH caches are separate. Package measurements.

0.1.7 demos: recorded in DSH Desktop with English UI and captions, using the local workspace candidate before the formal version bump. Release notes, provenance and media · Earlier public-package installation.

English DSH demo: Word, Excel sheets and fullscreen PowerPoint

Rotate and zoom 3D models, look around 360° photos and play panoramic video in the same sidebar. Full-color animated WebP · Full MP4.

English DSH demo: GLB and 3MF models, the Milky Way and 360-degree video

Version 0.1.9 includes File workspace in the same dsh-filens installation: session groups with real thumbnails, related files, and links back to the source message or question. Its switch is independent of sidebar Preview. Supports DSH 0.2.2-rc.1, alongside the previously validated rc.5/alpha.3 versions.

English DSH demo: session file groups, related files and navigation to the source question

Browser integration: single file or split modules

Preview 0.3.6: split ZIP 5.62 MiB, all-in-one ZIP 10.61 MiB. Download from v0.6.6. Deploy the complete split directory, or choose the all-in-one JS build. Keep the archive sidecars to enable RAR / 7z.

npm: filens-preview@0.3.6, 16.22 MiB download / 31.88 MiB installed, including both builds. Public registry checks.

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">
  // Deploy the entire extracted directory; the split build loads engines as needed.
  import { createPreview } from './filens.js';
  // The all-in-one build uses the same entry point with styles, WASM and workers included.
  // Keep the archive sidecars for RAR / 7z.

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

Deploy the extracted 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.

iOS / Android SDKs

SDK 0.1.6 / preview 0.3.6: iOS ZIP 5.64 MiB, Android ZIP 5.65 MiB. 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.

Format coverage

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.
PSD / PSB, AI / EPS / PS Saved composite images or vector PDF. 8-bit RGB/grayscale for Photoshop; bounded PostScript preview subset. Design limits.
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.

Bundle sizes and loading costs

Detailed bundle sizes and loading costs
Module / core Raw gzip Brotli
Conversion core WASM (Office detection) 927.9 KiB 414.3 KiB 334.3 KiB
Image / RAW core WASM 2915.6 KiB 940.3 KiB 713.2 KiB
Media / panorama preview 465.1 KiB 128.8 KiB 108.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.6 KiB 160.3 KiB 127.4 KiB
DWG reader WASM (on demand) 886.8 KiB 432.4 KiB 351.8 KiB
Raster preview WASM (on demand) 1747.7 KiB 717.4 KiB 537.7 KiB
PostScript WASM (optional) 2429.4 KiB 745.6 KiB 516.0 KiB
HEIC / HEIF decoder WASM 1423.8 KiB 470.2 KiB 344.5 KiB
Demo entry 241.8 KiB 69.5 KiB 58.1 KiB
Agent CLI demo UI 34.9 KiB 13.5 KiB 11.1 KiB
Shared vendor dependencies 813.1 KiB 229.7 KiB 192.1 KiB
PPTX / core runtime 385.3 KiB 108.2 KiB 91.8 KiB
Vue preview host 247.2 KiB 66.0 KiB 52.5 KiB
DOCX / XLSX / PDF 51.7 KiB 16.0 KiB 14.4 KiB
On-demand DOCX engine 74.6 KiB 20.1 KiB 18.1 KiB
Office attachments 31.4 KiB 12.1 KiB 11.0 KiB
Shared XML compatibility 27.2 KiB 8.9 KiB 8.0 KiB
Shared ZIP compatibility 41.5 KiB 12.7 KiB 11.6 KiB
Encrypted ZIP support 99.1 KiB 37.0 KiB 32.3 KiB
On-demand PDF engine 435.2 KiB 128.1 KiB 106.9 KiB
iWork preview 40.5 KiB 12.1 KiB 10.8 KiB
CAD / mind maps / diagrams 100.6 KiB 28.4 KiB 24.4 KiB
3D preview 109.0 KiB 31.7 KiB 27.7 KiB
glTF / GLB model loader 42.7 KiB 12.6 KiB 11.2 KiB
FBX model loader 43.9 KiB 14.1 KiB 12.6 KiB
OBJ model loader 8.5 KiB 2.9 KiB 2.6 KiB
MTL model loader 4.2 KiB 1.7 KiB 1.5 KiB
3DS model loader 8.4 KiB 2.8 KiB 2.5 KiB
LDraw model loader 24.0 KiB 8.3 KiB 7.3 KiB
USDZ model loader 8.5 KiB 2.6 KiB 2.4 KiB
VRML model loader 178.0 KiB 46.4 KiB 39.8 KiB
Media decoder loader 143.1 KiB 52.5 KiB 45.5 KiB
Archive preview 48.1 KiB 14.6 KiB 13.1 KiB
RAR / 7z extraction WASM (optional) 1089.9 KiB 429.8 KiB 332.3 KiB
Archive worker (optional) 51.5 KiB 18.2 KiB 16.3 KiB
Text / ebooks 18.1 KiB 6.9 KiB 6.1 KiB
iWork worker 884.9 KiB 183.4 KiB 153.3 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 461.8 KiB Brotli (1946.8 KiB raw / 548.9 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 DWG optimization audit records the compact CAD reader (443 KB gzip), direct drawing-model loading, and measurements across 13 drawings; the reader is included in the build measurements above.

The table above measures the v0.6.6 production demo build. 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 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 (requires local deployment; otherwise, open the Vercel online demo), then choose a sample or drop in a file. For hosting, see the Vercel guide.

Install on ZimaOS

ZimaOS: a personal cloud with FiLens integration

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

HEIF decoder source versions, rebuild steps, and Apple-edited 10-bit color regression: HEIF decoder build.

Show SOTA benchmark results

Updated November 5, 2026. 12 measured scenarios cover DSH, XLSX, ZIP, PPTX, RAW and STEP. Each workload shows its latest recorded FiLens result against the named baseline; measurement dates and stages are stated. Tiny examples and marginal gains remain in the full reports.

Complete DSH sidebar previews

Sample · first / cached median (ms) FiLens 0.1.3 DSH built in First-open speedup
PPTX 135 / 81 1830 / 124 13.56×
DOCX 111 / 94 1827 / 112 16.46×
PDF 190 / 77 329 / 110 1.73×

Ratios in this table describe first opens. PDF cached opens improve 1.43× (110 → 77 ms). Office and PDF use separate nine-round paired measurements.

Large-input parsing against specialized libraries

Larger parsing workload Baseline Baseline / FiLens median (ms) Speedup
XLSX · 2,000 × 64, 128,000 cells SheetJS CE 0.20.3 150.94 / 61.72 2.45×
XLSX · 8,000 × 64, 512,000 cells SheetJS CE 0.20.3 615.71 / 213.50 2.88×
ZIP · 10,000 entries, 18.34 MiB expanded JSZip 3.10.1 700.55 / 55.52 12.62×
ZIP · 2,500 entries, 36.23 MiB expanded JSZip 3.10.1 247.99 / 95.37 2.60×

Nine measured rounds after two warmups, alternating library order; all cell values or complete entry texts verified. These parser timings exclude rendering, imports, network and verification. The DSH rows include preview rendering. Results are limited to the named workloads and baselines; they do not establish a universal ranking or identical feature coverage. Methods, versions, raw samples and reproduction · Historical comparisons.

PPTX, RAW and STEP: latest recorded browser comparisons

Workload FiLens (ms) Baseline (ms) Speedup Measured
PPTX · 11.1 MB, 13 slides, complete parse 28.5 pptx-preview 1.0.7: 56.6 1.99× Oct 23–24
NEF · Nikon D3S, sensor → preview canvas 152.7 LibRaw-Wasm 1.6.0 half-size: 326.7 2.14× Oct 23–24
DNG · Pentax K-r, sensor → preview canvas 167.7 LibRaw-Wasm 1.6.0 fast half-size: 314.4 1.87× Oct 23–24
STEP · as1_pe_203 assembly, geometry import 61.2 occt-import-js 0.0.23: 195.0 3.19× Nov 1
STEP · tailturbine, geometry import 50.6 occt-import-js 0.0.23: 153.9 3.04× Nov 1

All dates are in 2026. RAW inputs have no embedded JPEG; preview resolution/tone differs from LibRaw. STEP compares parsing/tessellation and validated geometry, with different triangulations; scene construction and drawing are excluded. PPTX measures complete parsing. These are the latest recorded runs for each workload, with inputs/modules ready before timing. Browser methods, confidence intervals and raw evidence.

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

Star History Chart

—/ 5

No ratings yet

Manifest verification required

Commit 9f0e3824b6a4

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout