Harbly

A local-first manager for single-file HTML — collect, preview, search, and iterate on your AI-generated artifacts (Claude / ChatGPT / Gemini).

Status: v0.1 (P0 local core + AI workbench) · macOS first · Tech stack in TECH_STACK.md.

Download & install (macOS)

Download Harbly 0.1.0 — Apple Silicon .dmg (~14 MB)

1. Open the .dmg and drag Harbly into Applications.
2. First launch: this build is not yet notarized by Apple, so macOS blocks it once. Go to System Settings → Privacy & Security, scroll down, and click Open Anyway (on macOS 14 and older you can instead right-click the app → Open). Terminal alternative: xattr -d com.apple.quarantine /Applications/Harbly.app
3. On first run Harbly creates its library at ~/Harbly — a plain folder you own; your files stay there even if you uninstall.

Requires an Apple Silicon Mac (Intel/universal builds are not shipped yet). AI features are optional and bring-your-own: connect a local Claude Code install (runs through MCP, no extra key), or add your own API key (Anthropic / OpenAI / OpenRouter) in Settings.

What's in v0.1

• Your data is just a folder: a library is a plain directory on disk and the sidebar mirrors it. Organize in Finder, the app follows (filesystem watching + content-hash rebinding, so moved files never lose their history)
• Import: drag & drop or file picker; BLAKE3 content-hash dedup; name collisions auto-suffixed
• Inbox: new imports land in _inbox; archiving = moving into a target folder
• Sandboxed preview: a custom protocol injects a CSP that blocks all network by default; blocked external requests are counted and surfaced, with per-view one-time allow
• Thumbnails: hidden WebView + native WKWebView snapshots, generated by a background queue
• Full-text search (⌘K): SQLite FTS5 with jieba Chinese segmentation; hits in both titles and body text
• File operations with Finder semantics: multi-select (⇧ range / ⌘ toggle / ⌘A), inline rename with Enter, open via double-click / Space / ⌘↓, ⌘⌫ moves to Trash, drag to move (multi-drag as a group), ⌘C / ⌘V file copy-paste interop with Finder (⌥⌘V = move)
• Universal undo/redo (⌘Z / ⌘⇧Z): delete, move, rename, duplicate, create, import, and paste are all undoable and redoable; the menu bar shows live labels like “Undo Delete ‘xx’”; deletes go through NSFileManager with the Trash landing spot recorded, so undo restores files to their exact original path — no confirmation dialogs needed, even for folders
• Finder tag interop: tags are written to the file’s own xattr (_kMDItemUserTags), visible and searchable in Finder / Spotlight; tags added or removed in Finder sync back automatically; tags travel with files on copy, export, move, and backup — the database is only a query cache
• Six-language UI: 简体中文 / 繁體中文 / English / 日本語 / 한국어 / Español — instant switching in Settings, localized native menu bar and dynamic “Undo xx” labels, system language detected on first launch
• AI workbench: a conversational panel over your library — local agents (Claude Code / Codex CLI) or bring-your-own-key (Anthropic / OpenAI / OpenRouter); token-level streaming with live Markdown; every AI edit lands as a version of the file on disk
• Markdown alongside HTML: manage .md files in the same library with a WYSIWYG editor (Milkdown), autosave + session checkpoints, protocol-level thumbnail rendering
• .hdoc page documents: notes richer than Markdown — a fixed custom-element vocabulary rendered through the same sandboxed protocol, with a ProseMirror editor, three themes, and baked single-file export
• Favorites: star assets from the grid, sidebar tree, or viewer; the flag lives in the file’s own xattr (com.harbly.favorite) so it travels with copies, moves, and backups

Version history is not user-facing yet (product decision, 2026-07): the UI has been fully removed, but the engine still keeps complete snapshots silently under .harbly/versions/ (v1 on import + snapshots of external edits), so history reconnects whenever the feature returns. The list_versions / restore_version commands remain registered.

Development

pnpm install
pnpm dev:desktop     # run the desktop app in dev mode
pnpm build:desktop   # package the DMG
pnpm dev:landing     # landing site dev server (Astro, localhost:4321)
pnpm build:landing   # landing site static build
pnpm test:core       # core logic tests

Project layout (monorepo: pnpm workspace + Cargo workspace):

crates/harbly-core/        core logic (pure Rust: index / scan / FTS / versions / watch)
apps/desktop/              desktop app
  src/                     React frontend (Vite + Tailwind 4 + Zustand)
  src-tauri/               Tauri shell (IPC commands, sandbox protocol, thumbnail pipeline)
apps/landing/              landing site (Astro 5, static, zero client JS — not committed yet)

Library layout on disk

~/Harbly/
  your-folders/xxx.html    ← plain files: manage them with git or any sync tool, keep them even if you uninstall
  _inbox/                  ← inbox for new imports
  .harbly/                 ← app-private (index.db, versions/, thumbs/)

Roadmap

P0 local core (now) → P1 capture inlets (browser extension / MCP / inline text edits) → P2 cloud sharing → P3 team libraries → P4 AI workbench.

License: AGPL-3.0-only