Glyphdown

Google Docs for markdown files — real-time multiplayer editing, comments, suggestion mode, edit history, and a CLI built for AI agents.

Hosted at · source at .

The document of record is plain markdown text, collaboratively edited through a Y.Text CRDT. Docs are files: a doc’s canonical name is its filename — a slug ending in .md (e.g. the-garden.md), unique within its folder (or your root). The web UI shows the filename stem (Obsidian-style, no extension); the CLI uses the filename verbatim, so the same doc has the same file name on every machine, and glyphdown mv renames a doc locally and on the server in one step. See SPEC.md for the full product and architecture spec.

For AI agents

Agents (Claude Code, etc.) collaborate on docs through the CLI: clone a workspace, edit plain .md files, sync — edits merge through the CRDT, or land as reviewable suggestions.

• Install the CLI: npm i -g glyphdown (or one-off: npx glyphdown --help) — see packages/cli/README.md.
• Skill: skills/glyphdown/SKILL.md — install with glyphdown install-skill (targets ~/.claude/skills, ~/.codex/skills, and ~/.agents/skills; narrow with --claude / --codex / --agents). Also installable by copying/symlinking skills/glyphdown, or via the Claude Code plugin marketplace (.claude-plugin/marketplace.json, plugin glyphdown).
• Full guide: docs/agent-guide.md — every command, the sync decision matrix, exit-code recovery, suggestion lifecycle, asset rules, multi-agent etiquette.

Stack

• Editor: CodeMirror 6 with Obsidian-style live preview, bound to Yjs via y-codemirror.next
• Web app: TanStack Start (React)
• Backend: Cloudflare Workers + Durable Objects (one DO per document)
• Auth: GitHub + Google OAuth
• CLI: glyphdown pull / glyphdown push / glyphdown sync — edit docs (or whole folders of them) as local files, merged through the CRDT

Deployment

Pushes to main deploy automatically via GitHub Actions (.github/workflows/deploy.yml): the CI gate (typecheck, tests, web build — .github/workflows/ci.yml) runs first, then the deploy job applies pending D1 migrations (wrangler d1 migrations apply inkwell --remote — idempotent, exits cleanly when nothing is pending) and runs wrangler deploy. Deploys queue rather than race or cancel mid-flight, and the workflow can also be run manually from the Actions tab (workflow_dispatch). The deploy job never runs on forks or pull requests.

One-time setup — the workflow needs a Cloudflare API token in the CLOUDFLARE_API_TOKEN repo secret:

1. dash.cloudflare.com → My Profile → API Tokens → Create Token → start from the Edit Cloudflare Workers template.
2. Add the D1 → Edit permission and scope the token to the account that owns the inkwell worker (the account id is pinned in the workflow file — it is not a secret).
3. gh secret set CLOUDFLARE_API_TOKEN (paste the token when prompted).

Manual fallback (unchanged): from apps/web, run pnpm db:migrate:remote (applies D1 migrations) then pnpm run deploy (vite build + wrangler deploy) with a logged-in wrangler.