md-collab-editor 0.1.0__tar.gz

md_collab_editor-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+dist/

md_collab_editor-0.1.0/CLAUDE.md

@@ -0,0 +1,10 @@
+# MD Collaborative Editor
+
+Local GitHub-style markdown editor shared between the user (browser) and Claude (terminal). See README.md.
+
+- Package layout: code in `src/md_collab_editor/` (`server.py`, `static/`), installed as the `md-editor` command via `pyproject.toml` (hatchling, no dependencies). `docs/` is just a sample folder, not packaged.
+- Run: `uv run md-editor [folder-or-file]` (or `md-editor` once installed with `uv tool install`), serves http://127.0.0.1:8765. Default document root is the current folder; the user can switch the root at runtime with the in-app file browser (`/api/root`), so check the status bar or `/api/config` for the folder currently open.
+- **Collaborating on a document:** edit the `.md` file on disk directly with Edit/Write. The open editor reloads it live and flashes the change, so there is no need to go through the browser. Avoid rewriting the whole file while the user is typing; prefer targeted edits.
+- In-browser "Ask Claude" requests run `claude -p` from `src/md_collab_editor/server.py` (`ask_claude`, `SYSTEM_PROMPT`), with tools restricted to Skill and Read.
+- Front end: no build step; libraries come from CDNs (marked 12, CodeMirror 5, DOMPurify, highlight.js, KaTeX, mermaid 10, github-markdown-css).
+- Gotchas: DOMPurify strips attributes containing `-->` (so mermaid source is kept as element text); mermaid.render is not re-entrant (renders are queued); blur CodeMirror before calling setSelection from preview code, or its input poll re-types the selection and wipes markers.

md_collab_editor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gareth Nisbet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

md_collab_editor-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: md-collab-editor
+Version: 0.1.0
+Summary: Local GitHub-style markdown editor shared between you and Claude Code
+Project-URL: Repository, https://github.com/garethnisbet/MDColaboritiveEditor
+Project-URL: Issues, https://github.com/garethnisbet/MDColaboritiveEditor/issues
+Author: Gareth Nisbet
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,editor,gfm,markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# MD Collaborative Editor
+
+A local markdown editor that renders exactly like GitHub, with Claude built in. You can highlight any passage and ask Claude to rewrite, tighten, restyle or critique it, then accept the suggestion or keep the original.
+
+## Install
+
+Install it as a command with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install git+https://github.com/garethnisbet/MDColaboritiveEditor
+```
+
+Or run it once without installing:
+
+```bash
+uvx --from git+https://github.com/garethnisbet/MDColaboritiveEditor md-editor
+```
+
+`pipx install git+https://github.com/garethnisbet/MDColaboritiveEditor` works too. Upgrade later with `uv tool upgrade md-collab-editor`.
+
+## Run
+
+```bash
+md-editor                       # edit the .md files in the current folder
+md-editor ~/notes               # edit any folder
+md-editor ~/proj/README.md      # edit one file (its folder becomes the root)
+md-editor --port 9000 --no-browser
+```
+
+It needs only Python 3.9+ (standard library, no dependencies) and the `claude` CLI on your PATH; uv can't install `claude`, because it isn't a Python package. Without it, everything except *Ask Claude* still works. The page loads its libraries from a CDN, so the browser needs internet access.
+
+To work on the editor itself, clone the repo and run `uv run md-editor docs`, which uses the code in the checkout.
+
+## Working with Claude
+
+1. **Highlight** text in the editor or in the rendered preview. In the preview a pop-up opens straight away; in the editor click the small *✦ Ask Claude* pill or press <kbd>Ctrl</kbd>+<kbd>J</kbd>.
+2. **Choose** a preset (*My style*, *Improve*, *Tighten*, *Expand*, *Simplify*, *Fix grammar*, *More formal/casual*, *To bullets/prose*, *Critique*) or type your own instruction. An instruction ending in `?` is treated as a question: Claude replies with a comment and leaves the text alone.
+3. A **card** appears in the Claude panel, and the passage is highlighted in purple while Claude works and in amber when the suggestion is ready. Each card offers:
+   - **Changes / Preview / Edit**: a word-level diff, the rendered result, or a text box for tweaking it by hand;
+   - **Accept**: replace the passage (Ctrl+Z undoes it);
+   - **Keep original**: discard the suggestion;
+   - **Retry**: ask for a different version;
+   - **Refine…**: give feedback such as "shorter" or "keep the first sentence" and get a revised version.
+4. With nothing selected, the request applies to the whole document.
+
+You can run several requests at once, and you can keep editing while Claude works, because each card tracks its passage as the text moves. *My style* uses the `nisbet-writing-style` skill; any skill in `~/.claude/skills` appears as a preset. The model menu in the top bar picks Opus, Sonnet or Haiku.
+
+Requests run through `claude -p` (headless Claude Code), so they use your existing Claude login and no API key is needed.
+
+## Working with Claude Code in a terminal
+
+Documents are plain `.md` files on disk. When Claude Code, or anything else, edits a file, the open editor updates within about a second and briefly flashes the changed text. If you had unsaved edits at that moment, a banner asks which version to keep. The editor autosaves shortly after you stop typing (<kbd>Ctrl</kbd>+<kbd>S</kbd> saves at once).
+
+## Rendering
+
+Rendering covers GitHub-flavoured markdown: tables, task lists (click the boxes in the preview to tick them), strikethrough, autolinks, `> [!NOTE]`-style alerts, syntax-highlighted code, `$…$` and `$$…$$` maths (KaTeX), ```` ```math ```` blocks, ```` ```mermaid ```` diagrams, heading anchors and inline HTML (sanitised). The preview uses `github-markdown-css` in light or dark (◐ button).
+
+## Editing
+
+The toolbar covers headings, bold, italic, strikethrough, quotes, code, links, images, lists, task lists, tables and rules. Shortcuts: <kbd>Ctrl</kbd>+<kbd>B</kbd>/<kbd>I</kbd>/<kbd>K</kbd>, <kbd>Ctrl</kbd>+<kbd>F</kbd> to search, <kbd>Tab</kbd> to indent, and <kbd>Enter</kbd> to continue lists. Scrolling in the editor and the preview stays in sync, and clicking a preview block moves the cursor to it.
+
+## Opening files elsewhere
+
+Click **📂** in the top bar (or *Open…* in the file list, or press <kbd>Ctrl</kbd>+<kbd>O</kbd>) to browse the disk. Click folders to move through them (↑ goes to the parent, ⌂ goes home), or type or paste a path and press Enter. Clicking a `.md` file opens it and makes its folder the working folder, so the sidebar lists its neighbours and live sync keeps working. *Use this folder* switches to the current folder without picking a file. The arrow keys and Enter also work in the list.
+
+## Exporting to PDF
+
+Click **⬇ PDF** in the top bar. The document is rendered in GitHub's light style (even in dark mode) on A4 pages, with maths and diagrams included and without Claude's highlights. It is saved as `<name>.pdf` beside the markdown file and downloaded by the browser. Relative image links resolve because the page is printed from the markdown file's folder. This uses headless Google Chrome or Chromium; set `MDEDIT_CHROME=/path/to/chrome` if it isn't found on the PATH. For the browser's own print dialog, press <kbd>Ctrl</kbd>+<kbd>P</kbd>; the print stylesheet prints only the rendered document.
+
+## Files
+
+All code lives in `src/md_collab_editor/`:
+
+- `server.py`: HTTP server (file API, folder browsing and root switching, change events, `/api/ask` → `claude -p`, `/api/pdf` → headless Chrome)
+- `static/index.html`, `static/app.css`: layout and GitHub-style theme
+- `static/render.js`: markdown → HTML, with source offsets on every block so preview selections map back to the source
+- `static/app.js`: editor, sync, selection mapping, ask bar, suggestion cards and word diff

md_collab_editor-0.1.0/README.md

@@ -0,0 +1,77 @@
+# MD Collaborative Editor
+
+A local markdown editor that renders exactly like GitHub, with Claude built in. You can highlight any passage and ask Claude to rewrite, tighten, restyle or critique it, then accept the suggestion or keep the original.
+
+## Install
+
+Install it as a command with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install git+https://github.com/garethnisbet/MDColaboritiveEditor
+```
+
+Or run it once without installing:
+
+```bash
+uvx --from git+https://github.com/garethnisbet/MDColaboritiveEditor md-editor
+```
+
+`pipx install git+https://github.com/garethnisbet/MDColaboritiveEditor` works too. Upgrade later with `uv tool upgrade md-collab-editor`.
+
+## Run
+
+```bash
+md-editor                       # edit the .md files in the current folder
+md-editor ~/notes               # edit any folder
+md-editor ~/proj/README.md      # edit one file (its folder becomes the root)
+md-editor --port 9000 --no-browser
+```
+
+It needs only Python 3.9+ (standard library, no dependencies) and the `claude` CLI on your PATH; uv can't install `claude`, because it isn't a Python package. Without it, everything except *Ask Claude* still works. The page loads its libraries from a CDN, so the browser needs internet access.
+
+To work on the editor itself, clone the repo and run `uv run md-editor docs`, which uses the code in the checkout.
+
+## Working with Claude
+
+1. **Highlight** text in the editor or in the rendered preview. In the preview a pop-up opens straight away; in the editor click the small *✦ Ask Claude* pill or press <kbd>Ctrl</kbd>+<kbd>J</kbd>.
+2. **Choose** a preset (*My style*, *Improve*, *Tighten*, *Expand*, *Simplify*, *Fix grammar*, *More formal/casual*, *To bullets/prose*, *Critique*) or type your own instruction. An instruction ending in `?` is treated as a question: Claude replies with a comment and leaves the text alone.
+3. A **card** appears in the Claude panel, and the passage is highlighted in purple while Claude works and in amber when the suggestion is ready. Each card offers:
+   - **Changes / Preview / Edit**: a word-level diff, the rendered result, or a text box for tweaking it by hand;
+   - **Accept**: replace the passage (Ctrl+Z undoes it);
+   - **Keep original**: discard the suggestion;
+   - **Retry**: ask for a different version;
+   - **Refine…**: give feedback such as "shorter" or "keep the first sentence" and get a revised version.
+4. With nothing selected, the request applies to the whole document.
+
+You can run several requests at once, and you can keep editing while Claude works, because each card tracks its passage as the text moves. *My style* uses the `nisbet-writing-style` skill; any skill in `~/.claude/skills` appears as a preset. The model menu in the top bar picks Opus, Sonnet or Haiku.
+
+Requests run through `claude -p` (headless Claude Code), so they use your existing Claude login and no API key is needed.
+
+## Working with Claude Code in a terminal
+
+Documents are plain `.md` files on disk. When Claude Code, or anything else, edits a file, the open editor updates within about a second and briefly flashes the changed text. If you had unsaved edits at that moment, a banner asks which version to keep. The editor autosaves shortly after you stop typing (<kbd>Ctrl</kbd>+<kbd>S</kbd> saves at once).
+
+## Rendering
+
+Rendering covers GitHub-flavoured markdown: tables, task lists (click the boxes in the preview to tick them), strikethrough, autolinks, `> [!NOTE]`-style alerts, syntax-highlighted code, `$…$` and `$$…$$` maths (KaTeX), ```` ```math ```` blocks, ```` ```mermaid ```` diagrams, heading anchors and inline HTML (sanitised). The preview uses `github-markdown-css` in light or dark (◐ button).
+
+## Editing
+
+The toolbar covers headings, bold, italic, strikethrough, quotes, code, links, images, lists, task lists, tables and rules. Shortcuts: <kbd>Ctrl</kbd>+<kbd>B</kbd>/<kbd>I</kbd>/<kbd>K</kbd>, <kbd>Ctrl</kbd>+<kbd>F</kbd> to search, <kbd>Tab</kbd> to indent, and <kbd>Enter</kbd> to continue lists. Scrolling in the editor and the preview stays in sync, and clicking a preview block moves the cursor to it.
+
+## Opening files elsewhere
+
+Click **📂** in the top bar (or *Open…* in the file list, or press <kbd>Ctrl</kbd>+<kbd>O</kbd>) to browse the disk. Click folders to move through them (↑ goes to the parent, ⌂ goes home), or type or paste a path and press Enter. Clicking a `.md` file opens it and makes its folder the working folder, so the sidebar lists its neighbours and live sync keeps working. *Use this folder* switches to the current folder without picking a file. The arrow keys and Enter also work in the list.
+
+## Exporting to PDF
+
+Click **⬇ PDF** in the top bar. The document is rendered in GitHub's light style (even in dark mode) on A4 pages, with maths and diagrams included and without Claude's highlights. It is saved as `<name>.pdf` beside the markdown file and downloaded by the browser. Relative image links resolve because the page is printed from the markdown file's folder. This uses headless Google Chrome or Chromium; set `MDEDIT_CHROME=/path/to/chrome` if it isn't found on the PATH. For the browser's own print dialog, press <kbd>Ctrl</kbd>+<kbd>P</kbd>; the print stylesheet prints only the rendered document.
+
+## Files
+
+All code lives in `src/md_collab_editor/`:
+
+- `server.py`: HTTP server (file API, folder browsing and root switching, change events, `/api/ask` → `claude -p`, `/api/pdf` → headless Chrome)
+- `static/index.html`, `static/app.css`: layout and GitHub-style theme
+- `static/render.js`: markdown → HTML, with source offsets on every block so preview selections map back to the source
+- `static/app.js`: editor, sync, selection mapping, ask bar, suggestion cards and word diff

md_collab_editor-0.1.0/docs/welcome.md

@@ -0,0 +1,47 @@
+# Welcome
+
+This editor renders markdown the way GitHub does, and it has Claude built in. Highlight any passage, in the source or in the preview, and ask Claude to rewrite it, tighten it, change its style or just comment on it. Every suggestion arrives as a card with a word-level diff that you can **accept**, **keep the original**, retry or refine.
+
+## Things to try
+
+- [x] Open this file
+- [ ] Highlight the paragraph above in the preview and choose *Tighten*
+- [ ] Select some text and press <kbd>Ctrl</kbd>+<kbd>J</kbd> to type your own instruction
+- [ ] Edit this file from a terminal and watch the change appear here
+
+> [!NOTE]
+> Files live on disk, so Claude Code in a terminal can edit them too. The editor picks up changes within a second.
+
+> [!WARNING]
+> If both of you edit at once, the editor asks which version to keep.
+
+## Formatting
+
+| Feature | Syntax | Shown as |
+| --- | --- | --- |
+| Emphasis | `**bold**`, `_italic_`, `~~strike~~` | **bold**, _italic_, ~~strike~~ |
+| Inline maths | `$E = mc^2$` | $E = mc^2$ |
+| Link | `[GitHub](https://github.com)` | [GitHub](https://github.com) |
+
+Display maths:
+
+$$
+\mathbf{Q} = \mathbf{k}_f - \mathbf{k}_i, \qquad |\mathbf{Q}| = \frac{4\pi}{\lambda}\sin\theta
+$$
+
+```python
+def bragg(d, wavelength):
+    """Return the Bragg angle in degrees."""
+    return math.degrees(math.asin(wavelength / (2 * d)))
+```
+
+```mermaid
+flowchart LR
+    A[Highlight text] --> B[Ask Claude]
+    B --> C{Suggestion}
+    C -->|Accept| D[Document updated]
+    C -->|Keep original| E[No change]
+    C -->|Refine| B
+```
+
+Footnote-style asides and HTML such as <sup>superscript</sup> also work.

md_collab_editor-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "md-collab-editor"
+dynamic = ["version"]
+description = "Local GitHub-style markdown editor shared between you and Claude Code"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Gareth Nisbet" }]
+keywords = ["markdown", "editor", "claude", "claude-code", "gfm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Editors",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = []
+
+[project.scripts]
+md-editor = "md_collab_editor.server:main"
+
+[project.urls]
+Repository = "https://github.com/garethnisbet/MDColaboritiveEditor"
+Issues = "https://github.com/garethnisbet/MDColaboritiveEditor/issues"
+
+[tool.hatch.version]
+path = "src/md_collab_editor/__init__.py"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

md_collab_editor-0.1.0/src/md_collab_editor/__init__.py

@@ -0,0 +1,3 @@
+"""MD Collaborative Editor."""
+
+__version__ = "0.1.0"

md_collab_editor-0.1.0/src/md_collab_editor/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()