npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

riffledesk

v0.4.5

Published

Local-first 3D file browser (three.js card stack) with recursive full-text search — edits, renames and deletes are explicit, opt-in and undoable

Readme

RiffleDesk

本機用、以瀏覽為主的檔案瀏覽器:把一個資料夾翻成一疊卡片,讓 AI 剛幫你寫的檔一看就找得到、讀得到、也改得回去。

English: README.md

上面的示範全部跑在捏造的資料上(scripts/demo/make-demo.mjs 生的,一個虛構的四人工作室和他們的定價頁改版)。畫面裡沒有真實檔案、路徑、磁碟或對話。

為什麼有這個東西

跟 AI 一起做事,磁碟上會冒出你沒打過的字:筆記、草稿、改過的程式、你叫他寫的報告。接著最有趣的部分——讀它、判斷它、改它——發生在終端機或對話視窗,而那兩者都很不會呈現一份文件。

RiffleDesk 就是補這個洞的介面:

  • 找出 AI 給你的檔。 一個剛被寫進 60 個檔的資料夾沒有順序,卡片堆有:最新在前、縮圖一眼可讀、整個資料夾底下所有寫過的字都全文搜得到。還有一份「AI 最近給的」清單,來源是你自己本機的對話紀錄,所以「它十分鐘前寫的那個」是一次點擊,不是一行 find。
  • AI 把檔推到你面前。 agent 的 shell 裡一句 riffledesk open report.md,每個開著的分頁都會跳出來並捲到它指的行。但它不搶畫面:背景分頁會先壓著、響一聲,等你回來才顯示。
  • 你推回去。 改版模式裡,你直接在渲染出來的 HTML 上點「這個標題不對,把試用期長度寫清楚」,文字改了、備註加了、還編了號,然後按「交給 AI」。頁面旁就寫出一份清單,agent 用 riffledesk wait 接走、照著改,再把結果開出來給你看。

功能

瀏覽。 左欄是資料夾樹,中間是 three.js 立起來的卡片堆(卡片有畫好的縮圖),游標掃過會像手撥紙一樣把鄰卡撥開,點一下就飛到右邊的閱讀面板。滾輪或拖曳在超大資料夾上做虛擬捲動。類型 chips(.md、程式碼、表格、HTML、圖片…)和「只看有這些檔的資料夾」把卡片堆收窄,All 連二進位檔都進來。

閱讀。 markdown 渲染(消毒過)、HTML 用沙箱 iframe 或上色原始碼、JSON 美化、CSV/TSV/XLSX 變表格、圖片與 PDF 就地開。程式碼有上色和行號、八套配色、換行開關,閱讀區可以查找並上一個/下一個/全部標亮。

搜尋。 全文、遞迴,檔名和文字類檔的內容都搜,背後是常駐索引(node:sqlite FTS5 trigram),由背景 worker thread 增量爬。短查詢退回只搜檔名;結果會回讀檔案驗證,不給過期的東西。

編輯。 點 ✎(或 Ctrl+E)編輯正在讀的檔,Ctrl+S 存檔。寫回之前會比對磁碟版本:AI 這期間改過就跳差異對話框,不默默蓋掉。改名、刪除、存檔都能 Ctrl+Z 復原(刪除是進資源回收筒,絕不硬刪)。

多選。 Ctrl 點卡片選取,然後批次改名、刪除、複製路徑或整批推給 AI;單項失敗不會拖垮其他項。

改版模式(HTML)。 點、描述、編號。頁面在沙箱 iframe 裡附帶一支注入的 agent,每一筆改動都變成檔案旁的 <檔名>.changes.json,AI 用 riffledesk changes 讀。細節見 API 文件。

投影。 POST /api/project(CLI 打的就是這支)把一個檔開進每個分頁,可指定行號。背景分頁會壓著並只發一則通知。

疊。 riffledesk show a.md b.md --title "…" 把一組相關的檔一次交成一疊卡:只有這幾張,同資料夾的其他檔不會冒出來。它只跳通知、不切畫面;左欄留著最近的疊,/?pile=<id> 能重開。也可以 riffledesk search … --json | riffledesk show。

AI 整理的疊會完整顯示交付檔案,不受資料夾類型篩選影響。類型按鈕會標示「此疊顯示全部」;離開疊後恢復原本的資料夾篩選。疊旁數字表示仍存在的檔案數,只有空疊的數字才反灰。

其他: AI 對話清單(「這檔是哪則對話寫的?」)、釘選資料夾、把疑似金鑰的檔標出來的密鑰掃描,還有沒動作就完全停掉的 idle render loop。

安裝

npx riffledesk

Node ≥ 22.5(索引要靠 node:sqlite;舊版 Node 可跑但只能即時掃描)。執行期零相依。從 clone 跑:npm install && npm start。Windows 用 start.bat,macOS/Linux 用 start.sh。

預設只是瀏覽,只有你叫它寫才寫:存檔、改名、刪除,每個寫入都是明確的一次點擊,而且刪除進回收筒、救得回來。

伺服器只綁 127.0.0.1,開在 http://127.0.0.1:5177/。用 PORT、埠參數或 riffledesk --port 5180 換埠;--no-open 不開瀏覽器。重複啟動會沿用同一個埠上的服務。

啟動器開完就會結束,RiffleDesk 留在背景執行;關閉終端或 AI 助手不影響使用。到 設定 → RiffleDesk 可看版本、重新啟動或結束服務;這會影響連到該服務的所有分頁。結束後再次開啟 RiffleDesk 即可使用,不會自動設定開機啟動。

命令列也有 riffledesk status、riffledesk restart、riffledesk stop,都接受 --port N。更新 npm 套件後要重新啟動服務,已執行的舊程式才會換新版。0.3.0 以前的服務需先手動結束一次。開發時用 npm run dev 或 riffledesk --foreground 留在終端執行,按 Ctrl+C 結束。Windows 若在 Git Bash 被防毒阻擋,改用 riffledesk.cmd。

PowerPoint .pptx 可預覽投影片文字與圖片、顯示第一頁縮圖,並在閱讀區查找文字;動畫、SmartArt、母片效果及舊 .ppt 不支援,投影片內容也不納入全碟內文搜尋。

給 AI agent 的命令列

啟動器同時就是 agent 端的 CLI——這是這個工具對助手有用的另一半:

riffledesk open report.md --line 42     # 把檔推給所有已開分頁
riffledesk show a.md b.md --title "重試預算"   # 一次交一組檔(一疊)
riffledesk search "retry budget" --in ~/notes --ext .md --json | riffledesk show
riffledesk changes page.html            # 讀使用者的改版清單
riffledesk wait page.html               # 等使用者交過來
riffledesk --help

open 打 POST /api/project 並帶 X-RiffleDesk-CLI: 1 標頭(瀏覽器的跨站 POST 偽造不出來),回報推給幾個分頁;沒有分頁、或伺服器舊到沒這支端點時,改用預設瀏覽器開 /?open=<路徑>。兩個子命令都會先探測本機埠,沒人回應就背景無頭起一台。輸出全英文方便腳本解析;search 沒結果 exit 1、參數錯 exit 2。

教 agent 這套流程的 skill 放在 skills/riffledesk/。完整端點清單在 docs/API.md。

可選的 Stop 提醒(Claude Code)

agent 有時寫完要交付的檔(報告、網頁、試算表)就直接收尾,忘了給使用者看。CLI 內建一支 Stop hook,專門在這種情況提醒一次:

riffledesk hook install      # 合併進 ~/.claude/settings.json(先寫 .bak、其他 hook 不動)
riffledesk hook status       # 看有沒有裝(裝了 exit 0、沒裝 exit 1)
riffledesk hook uninstall    # 只移除我們這條

agent 收尾時 hook 才跑一次:掃對話紀錄尾巴,如果 Write/Edit 寫了交付型檔案(.md .html .svg .pdf .csv .png .jpg .docx .xlsx .pptx…),而且最後一句使用者訊息之後沒跑過 riffledesk open/show,就用正確指令提醒 agent 補交。不會遞迴觸發、平常完全不跑;任何錯誤都靜默結束,絕不卡住對話。設定檔其他內容一律不動;檔案不是合法 JSON 就拒絕(exit 2),不會覆蓋。

一般 Markdown 會自動套用書頁式閱讀排版,原稿不變。HTML 可以在同一份文件裡混合文字、插圖、圖解與可操作的 three.js 圖;程式由使用者按下執行才啟用。詳見交付能力與可選範例,不需要另外安裝技能,也不強制 agent 使用模板。

工具列的「類型」選單可直接複選,例如同時顯示 MD 與 TXT,重整後保留選擇。「HTML/互動 3D」包含 HTML 網頁;單獨的 JavaScript 仍屬程式碼。這裡只篩選顯示檔案,不限制 AI 產出格式。

左欄群組可以收合。對話優先顯示工具已儲存的標題或摘要,滑過可看使用者的第一句話,資訊按鈕可複製 Session ID 並找到原始紀錄。網頁模式不會被新交付通知切回檔案;連線檢查失敗時保留卡片與位置,恢復連線也不重載畫面。

隱私

  • 只走 loopback。 伺服器聽 127.0.0.1,只回 loopback 的 Host,跨站 API 呼叫一律拒絕(Sec-Fetch-Site+每個寫入都要 Origin),並且每個回應都帶 Cross-Origin-Resource-Policy: same-origin——外面的網頁讀不到你的檔。
  • 沒有遙測、不上雲。 什麼都不離開這台機器。(three.js、marked、DOMPurify、SheetJS 從 CDN 載、固定版本+SRI,所以「頁面本身」需要網路;highlight.js 是內附的,離線可用。)
  • 它讀哪些對話紀錄。 為了做「AI 最近給的」和對話清單,伺服器會在本機讀支援清單內各工具的寫檔紀錄(Claude Code、Codex、Gemini CLI、Cline/Roo Code/Kilo Code、Pi、Grok Build——位置見下表)。只抽檔案路徑、標題、時間,不上傳,解析結果按 size+mtime 快取。
  • 關掉它。 config.json 寫 convoRoots: [] 就完全不做對話掃描;convoRoots: [{kind, dir}] 可指向別的目錄。刪掉 index.db* 就清掉索引裡所有路徑名稱。
  • 瀏覽範圍預設是所有本機磁碟加上家目錄文件。這是刻意的寬;config.json 的 roots 可以收窄。

支援哪些 AI 工具

對話側欄讀的是各工具自己寫下的紀錄檔——跟終端機/IDE 無關,只看 AI 工具的紀錄檔放在哪。

| 工具 | 支援 | 紀錄位置 | |---|---|---| | Claude Code(CLI、VS Code/JetBrains 擴充、桌面 App 的 Code 分頁) | ✅ | ~/.claude/projects/*/*.jsonl | | Codex(CLI、桌面 App、VS Code 擴充) | ✅ | ~/.codex*/sessions/**/rollout-*.jsonl | | Gemini CLI | ✅ | ~/.gemini/tmp/<專案>/chats/**(GEMINI_CLI_HOME 可換家目錄) | | Cline/Roo Code/Kilo Code(VS Code 擴充,舊版面) | ✅ | VS Code globalStorage */tasks/<taskId>/api_conversation_history.json | | Pi(badlogic/pi-mono) | ✅ | ~/.pi/agent/sessions/**/*.jsonl(PI_CODING_AGENT_SESSION_DIR 可換) | | Grok Build(xAI 官方 coding agent) | ✅ | ~/.grok/sessions/*/*/updates.jsonl(GROK_HOME 可換) | | Cursor、Windsurf、GitHub Copilot、opencode(現行版)、Kilo Code(2026 改版)、superagent-ai/grok-cli | ❌ | SQLite/私有格式,不解析 | | Aider | ❌ | 各專案的 .aider.chat.history.md;用「最近改動」涵蓋 |

註:Cursor/Windsurf 自身歷史不解析,但裝在它們裡面的 Cline 家族延伸會被掃描(其 globalStorage 在掃描清單內)。

完整調查(每個位置、格式、來源網址、信心)在 docs/ai-sources.md。不在支援清單的工具:叫 AI 跑 riffledesk open <檔>/riffledesk show … 把檔案推進來,或用側欄的「最近改動(不確定是誰改的)」列——列出標記專案資料夾(有 AGENTS.md/CLAUDE.md/GEMINI.md/.claude/.cursor/.git,或同層 ≥5 個 Markdown)裡最近 7 天改過的檔案,扣掉確定是支援中的 AI 對話寫的。這列直接用既有索引查 mtime,不會再掃磁碟,需要索引在跑才看得到。

限制

  • 只看得到截圖的雲端助手碰不到這台伺服器。 CLI 要 agent 在同一台機器上有 shell。對跑在別處的聊天助手而言,這是你自己操作的瀏覽器,不是遠端端點。
  • 預設唯讀;只有四個寫入端點(reveal/open/rename/trash)加上存檔與釘選會動磁碟,而且刪除只進回收筒。
  • 文字編輯只收 UTF-8、≤5MB、文字類。非 UTF-8(Big5、UTF-16)、二進位檔、XLSX 只能看不能改。復原堆疊在記憶體、20 步、重開即失效。回收筒復原只支援 Windows。
  • XLSX 只顯示第一張工作表;PDF 只是嵌入預覽。
  • 執行中的 HTML 頁面裡的查找碰不到它的 DOM——先切回安全預覽或原始碼。
  • 超大資料夾(System32 等級)第一次列舉會回數 MB JSON,目錄快取只能緩解重複。
  • 前端搜尋框只過濾目前資料夾的檔名;遞迴全文搜尋走 /api/search。

相容性

Chromium、Firefox、Safari(後兩者最新版)。卡片堆需要 WebGL;不支援的電腦會顯示一張說明卡,不是卡片堆(樹、搜尋、閱讀和編輯都照常可用,檔案也照樣開得起來)。跑到一半掉 context(顯示卡驅動重置)時同一張說明卡會蓋住卡片欄,並給一顆重新載入。沒有 2D 備援,所以舊的 ?flat=1 書籤還能開,但已經沒有作用。伺服器 Windows 和 POSIX 都能跑;回收筒復原和在檔案總管中選取是 Windows 專屬。

平台備註

  • 不加設定能瀏覽什麼。 Windows:所有固定磁碟機(C:\、D:\…)。macOS:你的家目錄加上 /Volumes 下的外接磁碟(刻意排除指到系統根 / 的 Macintosh HD 別名與指到 /System/Volumes/Data 的 Macintosh HD - Data,避免整顆系統碟默默變成可瀏覽)。Linux/WSL:家目錄加上 /mnt/* 與 /media/<使用者>/*(udisks2 桌面另有 /run/media/<使用者>/*;查不出使用者時列出 /media/*)。範圍外的路徑(例如 /opt/data)在 config.json 的 roots 加一行即可(或用 pinned 釘進來)。
  • three.js 走 CDN(cdn.jsdelivr.net import map):第一次開頁需要網路,其餘全部離線本機。
  • macOS 跑測試。 單元測試:node --test --test-concurrency=1 "tests/*.test.mjs"(無原生相依;用埠 5179 與 5193–5196)。瀏覽器 e2e 會透過 tests/chrome-path.mjs 自己找 Chrome(/Applications 下的 Chrome/Chromium/Edge,擴充功能測試優先用 playwright 自帶 Chromium);要指定別支瀏覽器就設 CHROME_PATH,例如 CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" node tests/e2e.mjs。

設定

第一次啟動會產生 config.json(不進 git;config.example.json 是空白範本)。鍵有:roots(額外可瀏覽根目錄)、pinned(釘選,介面會寫回)、indexSkipDirs、indexMaxMB、indexContent、indexAgentRoots(自動把 AI agent 實際工作過的資料夾也納入索引:從本機 agent 的 session 紀錄與投過來/疊過的檔反推,預設 true)、indexRecrawlHours(全量重爬間隔,預設 24 小時;兩次之間靠 fs.watch 在 ~1.5 秒內保持索引新鮮)、secretScan、secretScanSkipDirs、convoRoots、browser。用 RIFFLEDESK_CONFIG 指向別的檔可以隔離一份設定。

自動索引 agent 工作資料夾

indexAgentRoots 開啟時,以有上限的本機 session 讀取自動加入 Claude Code、Codex CLI、Gemini CLI、Antigravity CLI、Grok CLI、GitHub Copilot CLI、Factory Droid、Qwen Code、Continue、Amp、Cline CLI,以及 Roo Code/Cline 延伸的工作資料夾。延伸支援 VS Code、Code - Insiders、Cursor、Windsurf、Antigravity、Antigravity IDE 與 VSCodium。開機時讀一次既有 session,之後監看已存在的 session 目錄;不輪詢,也不掃整顆磁碟。只抽取工作區路徑欄位(不讀權杖),限制檔案數與位元組數,支援 file URI 解碼;目錄不存在或 JSON 壞掉都會安靜略過。支援 COPILOT_HOME、FACTORY_HOME_OVERRIDE、CLINE_DATA_DIR、GROK_HOME、CONTINUE_GLOBAL_DIR 與 GEMINI_CLI_HOME 自訂位置。

開發

npm test              # 伺服器層(node --test,5179)
npm run test:e2e      # 瀏覽器端完整驗收(playwright,5178)
npm run test:regress  # 迴歸抽查,夾具全自建
npm run test:edit     # 編輯/查找/衝突(5184)
npm run test:project  # 投影(5188)
npm run test:select   # 卡片多選(5190)
npm run demo:make     # 生捏造的示範資料
npm run demo:record   # 從它重錄 docs/media

瀏覽器測試用 playwright-core 開已安裝的 Chrome,跑在 5178 以後的埠,夾具全建在暫存目錄,不會碰你真實的 config.json 或索引。

授權

MIT——見 LICENSE。