Phial

An HTML-native document manager — write with AI agents, read rich interactive docs.

_{Named after the Phial of Galadriel from The Lord of the Rings — "may it be a light to you in dark places, when all other lights go out."}

English · 简体中文

---

What is Phial?

Phial is an open-source document manager — think Typora / Obsidian, but the native format is HTML instead of Markdown. It treats HTML as an operable interface, not "Markdown with a coat of CSS":

• Stored & displayed as HTML — one document = one .html file. Portable, opens in any browser, zero lock-in.
• AI generates interfaces, not just documents — describe what you need in the built-in chat panel. If the task involves dragging, ranking, filtering, tuning, or comparing, you get a working board or tuner — not a tidy write-up.
• Your actions flow back to the AI — rendered docs use an injected window.phial bridge to send their current state (a reordered board, an edited prompt…) back into the conversation, closing the loop.

That is the core difference between HTML and Markdown: HTML carries layout, diagrams, interaction, and visual hierarchy — not just text. People reason by comparing, moving, filtering, and re-checking results; HTML catches those actions.

Features

🧩 Operable interfaces	AI-generated draggable boards, tuners, and comparisons — not static prose.
🔁 window.phial bridge	Documents report state and send results back to the AI for the next round.
🔌 Pluggable agents	Built-in OpenAI-compatible API, or a local CLI agent (claude / codex / gemini).
🧱 Block & source editing	Notion-style block editor (TipTap) with / commands, plus raw HTML / split / preview views.
🕸 Document structure	Graph view, outline, AI 30-second summaries, and single-doc auto-linking.
📚 LLM Wiki	Drops agent guides into your workspace so Claude Code can build semantic links across docs.
🛡 Sandboxed rendering	<iframe sandbox="allow-scripts"> + injected CSP; in-doc JS runs, network blocked by default.

Quick start

Prerequisites

Tool	Version	Check
Node.js	18+	node -v
Python	≥ 3.11	python --version
uv	latest	uv --version

Setup

# 1. Configure — copy the example env and fill in LLM_API_KEY etc.
cp .env.example .env

# 2. Install dependencies (root + frontend via npm, backend via uv)
npm run setup:all

# 3. Start both backend (:5001) and frontend (:3000)
npm run dev

Open http://localhost:3000. Run a single side with npm run backend / npm run frontend.

How it works

Phial/
├── backend/    # Flask app-factory + blueprints under /api/*, uv-managed
│   └── app/
│       ├── api/        # /api/documents, /api/workspace, /api/agents, /api/ai
│       └── services/   # workspace, llm_client, html_agent, cli_agent,
│                       # doc graph / summary / auto-link, agent_guide
└── frontend/   # Vue 3 + Vite + vue-router + vue-i18n + CodeMirror
    └── src/
        ├── views/        # Home, Editor (3-pane + side-rail), Graph (full-screen)
        └── components/   # FileTree, HtmlEditor, SandboxPreview, AiPanel, GraphCanvas…

• Backend — Flask (app factory, blueprints mounted at /api/*), business logic in services/; Python ≥ 3.11, dependencies managed by uv.
• Frontend — Vue 3 + Vite, /api proxied to the backend on :5001; HTML source edited with CodeMirror.
• Rendering — every document renders inside <iframe sandbox="allow-scripts"> (never allow-same-origin) with an injected CSP. In-document JS runs by default; network access is blocked (connect-src 'none') unless you allow external resources in Settings.
• Storage — documents live in a local workspace folder (git-friendly); config (workspace path, render flags, selected agent + model + env) lives in ~/.phial/settings.json.

The window.phial bridge

Phial injects a small script into every rendered document, exposing a global phial object (available when JS is enabled):

Method	Purpose
phial.setState(obj)	Report the current UI state; auto-attached as context to your next AI message.
phial.sendToAgent(text, obj?)	Send a result back to the AI and trigger a new round — wire it to a primary button.
phial.emit(name, data?)	Fire a lightweight one-off event to the host.
phial.ready() / phial.onData(cb)	Optional: signal init complete / receive host-provided data.

The authoring AI knows this API, so "prioritize these tickets" yields a draggable board with export. Two playable examples ship on the home screen: a priority board and a prompt lab.

Roadmap

• Local workspace + .html document CRUD
• Three-pane editor: file tree / HTML source / live sandboxed preview
• AI panel: chat → streaming HTML generation → auto-render
• window.phial bridge (setState / sendToAgent) + interactive example docs
• Pluggable agents: built-in LLM API / local CLI (Claude Code, Codex, Gemini) with Settings panel
• Per-document context: bind code/note folders, fine-grained file selection, cross-doc references
• Notion-style block editor (TipTap): / commands, drag handles, Markdown shortcuts, tables, widgets
• Document structure: graph, outline, AI 30-second summaries, single-doc auto-linking
• LLM Wiki: agent guides written into the workspace for deep semantic linking
• Finer-grained CLI streaming; let the agent edit files directly
• Full-text search & tags
• More built-in templates (schedules, comparisons, checklists, forms…)
• Expose an MCP server so external agents can drive Phial
• Export (single-file HTML / PDF / Markdown) & version history

License

MIT (tentative).