discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
linyimin0812/folyn · source
Snapshot 0 · 2026-11-04T12:47:28Z · TypeScript ·
Content fingerprint
b1920628b97c250313be6ed8a4b123915eed39c3ec6afe049a17dc53c7f454c9GitHub description at capture
Local-first, vault-isolated, AI-native knowledge workspace. Markdown, whiteboards, ER diagrams & mind maps in one editor, with Claude Code / Codex / Gemini CLI agents wired in. Built with Tauri 2 + React.
README at capture
[English](README.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Español](README.es.md) <h1 align="center">Folyn Editor</h1> <p align="center"> Local-first · Vault-isolated · AI-native<br/> Local-first, vault-based, AI-native knowledge workspace. </p> <p align="center"> <img alt="platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-blue" /> <img alt="downloads" src="https://img.shields.io/github/downloads/linyimin0812/folyn/total?label=downloads" /> <img alt="stack" src="https://img.shields.io/badge/Tauri-2-orange" /> <img alt="license" src="https://img.shields.io/badge/license-MIT-green" /> </p> --- > One app, all your context. Isolate each set of data in a Vault, fit markdown, whiteboards, ER diagrams, and mind maps into one editor, and wire AI agents straight into your workflow — everything stays on your own devices. ## For Users ### First-run notes The app is not code-signed; the OS will block it on first launch. Dismiss as follows: - **Windows**: You'll see a SmartScreen "Windows protected your PC" warning on first run. Click **More info → Run anyway**. - **macOS**: If "can't be opened" or "damaged" appears after install, run in Terminal: ```bash xattr -cr /Applications/Folyn.app ``` Then reopen from Launchpad. ## Why Folyn - **Vault multi-vault isolation** — Open a separate vault for each project or note set. Data stays independent, switch anytime. Your local device is the single source of truth. - **Multi-format editing** — Markdown (with container extensions: Button / Callout / Card / Tabs / Timeline / Steps / Grid / FilePreview / StatusTag / Collapsible, plus Graphviz / Mermaid / PlantUML diagram containers), rich text, CSV, JSON, markmap mind maps, dbml ER diagrams, drawio architecture diagrams, excalidraw hand-drawn whiteboards, graphviz DOT — one editor handles them all. - **Universal preview** — Office documents, audio/video, archives, e-books, presentations and drawings — view them without leaving Folyn. - **Deep AI integration** — Built-in adapters for six CLI agents: Claude Code, Codex CLI, Gemini CLI, Opencode, Pi Code Agent, Qoder. Switch freely across model vendors, no vendor lock-in. - **Desktop pet assistant** — A resident desktop companion that pushes schedule reminders and task-change notifications; click to bring up a chat with the LLM. - **In-app terminal** — Open a terminal inside Folyn and let Claude Code / Codex / other CLI agents read and write the current document — no window switching. - **Activity collection** — Collector extensions record your day — window switches, file changes, GitHub activity, webhook events — into a per-vault local database; review it on a timeline and relations graph, and generate daily/weekly/monthly reports as vault notes (optionally AI-written). - **Extension system** — Microkernel + extension SDK architecture. Rich text, DBML, file viewer, and activity collectors ship as extensions, translation is built in; third-party extensions supported. - **Voice input** — Speech-to-text with automatic polish, pasted straight to the cursor (currently macOS only). ### Vault multi-vault isolation Open a separate vault for each project or note set. Each vault is its own data space — notes, attachments, and extension configs are stored independently; switching vaults is like switching a whole workspace. Data stays on the local device; no cloud account required. <p align="center"> <img src="docs/assets/screenshots/vault-1.png" alt="Vault switching" width="860" /> </p> ### Multi-format editing - **Markdown** — Standard syntax + a set of container extensions: Button / Callout / Card / Collapsible / FilePreview / Grid / StatusTag / Steps / Tabs / Timeline, plus Graphviz / Mermaid / PlantUml diagram containers - **Rich text** — WYSIWYG, for layouts that don't need markdown syntax - **Structured data** — CSV, JSON, edited directly - **Mind maps** — markmap, markdown outlines auto-rendered as visual structure - **Modeling & diagrams** — dbml (ER) / drawio (architecture, flow) / excalidraw (hand-drawn whiteboard) / graphviz (DOT) / plantuml / mermaid <p align="center"> <img src="docs/assets/screenshots/editing-2.png" alt="Markdown editor with container extensions" width="860" /> </p> ### Universal preview View Office documents, audio/video, archives, e-books, presentations and drawings without leaving Folyn — no extra software required. <p align="center"> <img src="docs/assets/screenshots/viewing-1.png" alt="Full-format preview" width="860" /> </p> ### Deep AI integration No vendor lock-in — mainstream CLI agents adapted straight into the editor: - **Claude Code** - **Codex CLI** - **Gemini CLI** - **Opencode** - **Pi Code Agent** - **Qoder** Configure CLI paths in Settings → AI. Switch freely across model vendors by task or preference. <p align="center"> <img src="docs/assets/screenshots/ai-1.png" alt="AI integration" width="860" /> </p> ### Desktop pet assistant Resident on desktop, pushes schedule reminders and task changes to the foreground; click to bring up the LLM chat window and ask anytime without breaking your flow. External apps (scripts, cron, CI) can trigger pet notifications via a local HTTP API — default `127.0.0.1:17382`, `POST /pet/action` pushes a bubble, supporting `target` navigation, `launch` to open a URL/app, and `actions` for bubble buttons. See [`docs/pet-notify-api.en.md`](docs/pet-notify-api.en.md). <p align="center"> <img src="docs/assets/screenshots/pet-1.png" alt="Desktop pet" width="860" /> </p> ### In-app terminal Open a terminal panel inside the Folyn workspace, side-by-side with the editor, file paths auto-synced. Claude Code / Codex CLI / other agents can modify the current document directly; AI edits appear in the editor immediately. Command output can be pasted back at the cursor — "edit → invoke → paste back" collapses into one pipeline. <p align="center"> <img src="docs/assets/screenshots/terminal-1.png" alt="In-app terminal" width="860" /> </p> ### Activity collection Collector extensions from the extension store record what happens on your machine — frontmost window changes, file create/modify/delete, GitHub commits/PRs/issues, and events pushed from external tools via a local webhook — into a database stored inside the vault. Nothing leaves your device. The Activity tab turns raw events into a day timeline and an entity relations graph (people, meetings, repositories, documents, tasks). Daily, weekly, and monthly reports are written as markdown notes in the vault; with a custom prompt the report body is generated by the LLM instead of a fixed template, and the desktop pet can notify you when a report is ready. <p align="center"> <img src="docs/assets/screenshots/activity-collect-time-line.png" alt="Activity timeline" width="860" /> </p> <p align="center"> <img src="docs/assets/screenshots/activity-collect-relations.png" alt="Activity relations graph" width="860" /> </p> Each collector can be enabled/disabled separately with its own polling interval — or write your own with the extension SDK. ### Extension system Microkernel + extension SDK architecture; the core stays lean and features load on demand: - **Translation** — Multilingual content processing (built in) - **Rich text / DBML / file viewer** — Editing and viewing extensions from the extension store - **Activity collectors** — Window activity / files / GitHub / webhook collectors from the extension store record events for the Activity tab Third-party extension extensions supported; see `docs/extensions.html`. <p align="center"> <img src="docs/assets/screenshots/extension-system.png" alt="Extensions" width="860" /> </p> ### Voice input Speech is transcribed to text in real time and auto-polished — removing filler and pauses — then pasted at the cursor. Currently macOS only; Windows not yet supported. <p align="center"> <img src="docs/assets/screenshots/voice-1.png" alt="Voice input" width="860" /> </p> ## For Developers ### Tech Stack | Layer | Technology | |-------|-----------| | Shell | Tauri 2 (Rust) | | Frontend | React 18, Vite 6, TypeScript | | Editor | CodeMirror 6 | | Markdown | unified / remark / rehype pipeline | | State | Zustand 5 | | Styling | Tailwind CSS 3 | | Monorepo | pnpm workspaces | ### Project Structure ``` folyn/ ├── apps/ │ └── desktop/ # Tauri desktop app │ ├── src/ # React frontend │ │ ├── components/ # shell, editor, AI, sidebar, file-types, ... │ │ ├── editor/ # CodeMirror extensions │ │ ├── hooks/ # React hooks │ │ ├── store/ # Zustand stores │ │ └── utils/ # Utility modules │ └── src-tauri/ # Rust backend (Tauri commands) ├── packages/ │ ├── cli-adapter/ # AI CLI adapter abstraction (Claude / Codex / Gemini / Opencode / Pi / Qoder) │ ├── container-extensions/ # Markdown container directive extensions │ ├── extension-host/ # Extension host runtime │ ├── extension-sdk/ # Extension SDK for third-party authors │ ├── create-folyn-extension/ # Extension scaffolding CLI │ └── vault-provider/ # Vault storage provider abstraction ├── package.json ├── pnpm-workspace.yaml └── tsconfig.base.json ``` ### Extension Points - **`cli-adapter` package** — Implement the adapter interface to plug in a new CLI Agent - **`container-extensions` package** — Custom `:::directive` container extensions, registered to the slash menu - **`vault-provider` package** — Custom storage backends (beyond local / GitHub / WebDAV / S3) - **`extension-host` + `extension-sdk`** — Third-party extensions register capabilities via the SDK (published on npm as [`folyn-extension-sdk`](https://www.npmjs.com/package/folyn-extension-sdk)); the microkernel loads them on demand - **`create-folyn-extension`** — Scaffolding CLI to quickly start a new extension - **File types** — Register a new Handler under `apps/desktop/src/components/file-types/` to extend file types See `docs/extensions.html` for details. ### Architecture Diagrams Design diagrams for the extension system and the activity collection pipeline (editable sources live in `docs/assets/diagrams/`): <p align="center"> <img src="docs/assets/diagrams/en/architecture.svg" alt="Architecture" /> </p> **Microkernel + extensions** — the extension host runtime mediates between feature extensions and the Rust microkernel's capability services; third-party extensions enter through the sandbox isolation layer. <p align="center"> <img src="docs/assets/diagrams/en/extension-tiers.svg" alt="Extension trust tiers" /> </p> **Trusted vs sandbox extensions** — trusted packages are TOFU-pinned and run in the host main realm; sandbox packages run inside an opaque-origin iframe with no DOM or Tauri access. <p align="center"> <img src="docs/assets/diagrams/en/extension-rpc.svg" alt="Extension RPC protocol" /> </p> **postMessage RPC protocol** — request/response, host push, and reverse command invocation across the host/iframe boundary, with per-call permission gating. <p align="center"> <img src="docs/assets/diagrams/en/activity-collector.svg" alt="Activity collectors" /> </p> **Activity collectors** — the poll/webhook runtime drives the collect → redact → ingest → cursor-advance loop; the cursor only moves after a successful push. <p align="center"> <img src="docs/assets/diagrams/en/activity-schema.svg" alt="Activity database schema" /> </p> **Activity database schema** — per-vault SQLite tables for events, entities, relations, collector cursors, and run history. <p align="center"> <img src="docs/assets/diagrams/en/sdk-surface.svg" alt="Extension SDK surface" /> </p> **SDK surface** — the type contracts published as [`folyn-extension-sdk`](https://www.npmjs.com/package/folyn-extension-sdk): the Extension entry, the ExtensionApi capability boundary (vault, editor, AI, network, terminal, export, commands, events, storage, env, registries), contributes declaration points, and dev tools. ## Getting Started ### Prerequisites - [Node.js](https://nodejs.org/) >= 20 - [pnpm](https://pnpm.io/) >= 9 - [Rust](https://www.rust-lang.org/tools/install) (latest stable) - Tauri 2 system deps — see [Tauri prerequisites guide](https://v2.tauri.app/start/prerequisites/) ### Install & Run ```bash # Install dependencies pnpm install # Start development (frontend + Tauri dev window) pnpm dev # Build the frontend only pnpm build # Build the desktop app (platform-specific installer) pnpm build:app ``` ## License MIT