Keeping docs, RFCs, and architecture diagrams in local Markdown files backed by Git is the ideal workflow—until you need to collaborate. Git is built for lines of code, not prose. The moment you need real-time feedback on an RFC or a system diagram, you're usually forced to copy-paste everything into Confluence or Google Docs, fracturing your source of truth.
I built CollabMD to bridge this gap. It adds a real-time multiplayer layer directly on top of your existing local files, without requiring a database migration or proprietary formats.
How it works (Local Swarming):
Run `npx collabmd@latest ~/my-vault` inside your local repo. It spins up a local Node server and a browser-based IDE. Yjs handles the CRDT state in memory. You share the URL (it includes an optional Cloudflare tunnel), and your team can instantly jump in and co-edit the files.
Because engineering docs need more than text, I built in native diagram support:
- Mermaid & PlantUML: Co-edit the plaintext syntax and see the server-rendered preview update instantly.
- Excalidraw: Full multiplayer canvas integration. You edit the diagram together directly, complete with live cursors, presence, and a "follow" mode that syncs your viewport to another user.
How it works (Self-Hosted Team Gateway):
You can also deploy it as a persistent team gateway. It ships with a Docker image (and Coolify instructions) that securely bootstraps a private Git repo using your SSH keys. When the collaboration session is done, you use the built-in Git UI to stage, commit, and push the actual files back to your repo. The filesystem remains the absolute source of truth.
(Note on the demo: This is an open public sandbox, so expect multiplayer chaos. For the Git UI, I've intentionally left the upstream blank. You can stage and commit locally on the server to see how the UI feels, but pushes will intentionally go nowhere.)
Current Limitations & Roadmap
Right now, the app supports a basic shared password (`--auth password`), but enterprise-grade identity is still a WIP. If you want to host sensitive data publicly today, you should put the container behind an authenticating reverse proxy like Cloudflare Access.
My immediate roadmap to make the Team Gateway seamless:
1. OIDC Authentication: Native identity provider support so you don't need a heavy reverse-proxy setup.
2. Dynamic Git Attribution: Right now, the host's SSH key authors all commits. Once OIDC is in, I plan to intercept manual commits and inject the user's verified credentials into the `git commit --author` flag, preserving `git blame`.
I'd love to hear how others are handling the friction between keeping a strict Git-backed workflow while needing real-time collaboration. Specifically, if anyone has tackled the race condition between active CRDT memory states and underlying filesystem changes during a pull, I'm all ears.
Keeping docs, RFCs, and architecture diagrams in local Markdown files backed by Git is the ideal workflow—until you need to collaborate. Git is built for lines of code, not prose. The moment you need real-time feedback on an RFC or a system diagram, you're usually forced to copy-paste everything into Confluence or Google Docs, fracturing your source of truth.
I built CollabMD to bridge this gap. It adds a real-time multiplayer layer directly on top of your existing local files, without requiring a database migration or proprietary formats.
How it works (Local Swarming): Run `npx collabmd@latest ~/my-vault` inside your local repo. It spins up a local Node server and a browser-based IDE. Yjs handles the CRDT state in memory. You share the URL (it includes an optional Cloudflare tunnel), and your team can instantly jump in and co-edit the files.
Because engineering docs need more than text, I built in native diagram support:
- Mermaid & PlantUML: Co-edit the plaintext syntax and see the server-rendered preview update instantly.
- Excalidraw: Full multiplayer canvas integration. You edit the diagram together directly, complete with live cursors, presence, and a "follow" mode that syncs your viewport to another user.
How it works (Self-Hosted Team Gateway): You can also deploy it as a persistent team gateway. It ships with a Docker image (and Coolify instructions) that securely bootstraps a private Git repo using your SSH keys. When the collaboration session is done, you use the built-in Git UI to stage, commit, and push the actual files back to your repo. The filesystem remains the absolute source of truth.
Repo: https://github.com/andes90/collabmd
Live Demo: https://collabmd.andesyudanto.com
(Note on the demo: This is an open public sandbox, so expect multiplayer chaos. For the Git UI, I've intentionally left the upstream blank. You can stage and commit locally on the server to see how the UI feels, but pushes will intentionally go nowhere.)
Current Limitations & Roadmap Right now, the app supports a basic shared password (`--auth password`), but enterprise-grade identity is still a WIP. If you want to host sensitive data publicly today, you should put the container behind an authenticating reverse proxy like Cloudflare Access.
My immediate roadmap to make the Team Gateway seamless:
1. OIDC Authentication: Native identity provider support so you don't need a heavy reverse-proxy setup.
2. Dynamic Git Attribution: Right now, the host's SSH key authors all commits. Once OIDC is in, I plan to intercept manual commits and inject the user's verified credentials into the `git commit --author` flag, preserving `git blame`.
I'd love to hear how others are handling the friction between keeping a strict Git-backed workflow while needing real-time collaboration. Specifically, if anyone has tackled the race condition between active CRDT memory states and underlying filesystem changes during a pull, I'm all ears.