[Herdr Hands-on] Building Kalamos: A Typora-style macOS Markdown Editor in 3 Days with Claude Code as PM, Parallel Development,
Previously In the previous three Herdr practical articles (First time using Herdr, Using two agy Panes for record2gif, Writing my own Herdr mod: review-queue), I went from a single backend Code Review all the way to cr
Previously
In the previous three Herdr practical articles (First time using Herdr, Using two agy Panes for record2gif, Writing my own Herdr mod: review-queue), I went from a single backend Code Review all the way to creating a macOS screen-to-GIF tool in one day, and even wrote a dedicated Herdr queue panel for my own workflow.
After validating the rhythm of "Claude Code as PM on the left, multiple Panes writing code in parallel on the right," this time I wanted to take a real-world, high-complexity topic used daily to stress-test this process:
Following a complete
docs/PRD.md, build a Typora-style, single-window What-You-See-Is-What-You-Mean (WYSIWYM) macOS Markdown editor.
I named it Kalamos (Ancient Greek κάλαμοΟ, a reed pen used for writing on papyrus)βthe interface is like a quiet piece of paper, hiding Markdown syntax symbols when the cursor leaves. It is completely free, offline, requires no account, has no telemetry, and saves as clean standard GFM.
As a result, from starting work on 2026-11-19 to 2026-11-21, I completed all M1βM3 milestones within three days, accumulating 33 Issues and 38 merged PRs. I went from the project skeleton all the way to MIT open source, launched a four-language product page, and officially released v0.1.1.
The results first:
- GitHub Repo: kkdai/Kalamos
- Four-language Product Page: kkdai.github.io/Kalamos
- Official Release Download: Release v0.1.1
I. What did Kalamos do? Tech Stack and M1βM3 Milestones
Before starting, I defined the tech stack, keeping the principles consistent with the PRD: Local-first, standard GFM, CJK-friendly, and fully offline.
| Layer | Tech Stack | Description |
|---|---|---|
| Desktop Framework | Tauri 2 (Rust) | Lightweight macOS native shell, file system monitoring, secure saving, native PDFKit export |
| Frontend Core | Vite + TypeScript | Fast builds, combined with in-memory IPC mock for running dev and E2E directly in the browser |
| Editing Engine | CodeMirror 6 + @lezer/markdown
|
GFM base with custom math, CJK emphasis, front matter, and footnote syntax extensions |
| Math & Diagrams | MathJax 3 + Mermaid (strict + DOMPurify) |
Fully offline SVG rendering; supports flow and sequence in addition to Mermaid |
| Other Components |
gemoji + Pandoc (Optional) |
Offline :emoji autocomplete; supports exporting/importing DOCX / EPUB / LaTeX if Pandoc is installed |
Following the priorities in docs/PRD.md, the entire product was pushed through three milestones, eventually completing M1βM3:
| Milestone | Covered Features |
|---|---|
| M1 (Core Editing) | Single-window real-time preview and source code mode (Cmd+/), lists and checkable task lists, links and heading bookmarks, GFM visual tables, 100+ language code blocks, offline MathJax formulas, inline image display and drag-and-drop paste, sidebar (file tree / file list / outline), Papyros / Melan themes and custom CSS, atomic saving (temp + rename) and crash recovery |
| M2 (Delivery) | Native PDF export (including nested heading bookmarks, math, and diagram rendering), Pandoc multi-format export and import (DOCX / ODT / LaTeX / MediaWiki / EPUB), Mermaid / flowchart / sequence diagrams, image resizing and static blog root directory, YAML Front Matter / footnotes / [TOC], Ataraxia focus mode (F8) and Stichos typewriter mode (F9), word count and selection statistics |
| M3 (Optimization) | Offline Emoji autocomplete, auto-pairing for CJK brackets and Markdown symbols, custom CLI image uploader (restricted to config file for security) |
II. Multi-Agent Collaboration Mode: PM, Dual Worktrees, and "Seamless Switching when Quota is Exhausted"
The collaboration architecture this time followed the methods polished in previous articles but with stricter discipline, incorporating my own /herdr-pm and /herdr-coder skills:
- Left is Claude Code (PM / Reviewer): Reads PRD, breaks down Issues, defines interface contracts, reviews diffs, adds tests, runs validation. Only the PM touches git (create branch β commit β open PR β wait for CI β squash merge).
-
Right has two coder Panes in Herdr (
kalamos-a,kalamos-b): Each is bound to an independent git worktree (Kalamos.wt/a,Kalamos.wt/b). Files are completely isolated, usinghc send/hc waitfor asynchronous task assignment and reporting. -
Added a hygiene rule: This time I specifically required the PM to "Close the Pane once the work is done." After each task is merged into
main, the PM executeshc kill+hc rmto clear the corresponding Pane, preventing the screen from becoming cluttered.
Practical Episode: What to do when the agy quota runs out?
When developing a large project halfway, a realistic problem is bound to occur: initially, both coder Panes were running agy (Gemini). After several rounds of major features, an Individual quota reached error popped up.
In a traditional single-tool workflow, you'd probably have to stop and wait for the quota to recover or restart the entire conversation context. But in Herdr, because the worktree is still there, the Issue specs are still there, and the PM's grasp of progress is still there, the PM simply replaced the exhausted coder with Claude Code (claude --permission-mode auto) in the same worktree to take over. The entire development pipeline continued without interruption.
This again validates the advantage of the TTT (Terminal Text Tool, AI Terminal Editor) pipeline discussed in the first article: Agents are swappable execution units; the process and state remain in the worktree, Issues, and the PM's hands.
III. The First Batch of "Landmines" Caught During User Testing (#49, #54, #56)
Just like with record2gif, after all features were done and unit tests were green, the real test was "me personally opening it to type a few words." Typing immediately caught three critical issues:
1. WYSIWYM was "not Typora-like enough" (#49, #54)
When I tried typing, I immediately complained: "A WYSIWYG editor should show Markdown effects directly. For example, - should immediately display as a list, and *test* should immediately become italic!"
The original implementation was too conservative; as long as the cursor was on a line, the syntax markers for the entire line were exposed. It felt similar to a dual-pane editor. After receiving the report, the PM didn't rush to create Issues based on imagination, but first used a Playwright script with a real keyboard to type and capture screenshots to reproduce the behavior. After confirming the exact behavior, it was split into two P0 Issues:
-
#49 (Block Markers):
-,1.,- [],##,>render into lists/headings/quotes immediately after typing a space. The source code is only exposed if the cursor is actually on the marker itself; pressing Enter on an empty list item or Backspace after a marker naturally exits the list or quote. -
#54 (Inline Markers):
*italic*,**bold**,coderender and hide symbols the moment the closing character is typed. The source code only expands if the cursor is strictly inside the span; pressing Backspace behind a rendered span expands the syntax first before deleting, fully restoring the Typora feel.
2. Occasional CI Error: RangeError after IME Composition (#56)
Before and after adding GitHub Actions CI (#53), tests occasionally threw a tricky error:
RangeError: Position 55 is out of range for changeset of length 53
Tracing into the mapPos in blocks.ts revealed the root cause: in the StateField handling for footnotes, diagrams, and math, the IME composition branch was directly copying the old parsedTo instead of applying changes.mapPos to it. If the input method composition shortened the document length, the old position would exceed the end of the document, causing the next transaction's mapPos to explode.
The fix was solid: besides adding correct mapping to all three composition branches, I extracted src/editor/positions.ts so that all stored positions in the project follow the same protection layer:
export function clampPos(pos: number, length: number): number {
if (!Number.isFinite(pos) || pos < 0) return 0;
return pos > length ? length : pos;
}
export function mapPosClamped(changes: ChangeDesc, pos: number, assoc = -1): number {
return clampPos(changes.mapPos(clampPos(pos, changes.length), assoc), changes.newLength);
}
Furthermore, the PM required the coder to first write a regression test that failed on the old code (3 cases each for vitest and e2e, then repeated with Playwright --repeat-each 20) to confirm the fix was green before allowing the merge.
IV. The Big Projects: The Reed Pen Icon and Splitting "Table WYSIWYM" into Parallel Halves
Once the core experience was stable, I threw in two requirements I cared about most: one was the "face" of the app (App Icon), and the other was the "final boss" of Markdown editors (Visual Tables).
1. Hand-written SVG Reed Pen App Icon (#58)
I wanted a beige-toned reed pen icon echoing the name Kalamos. Instead of installing extra image conversion packages, I had the coder follow a clean pipeline:
- Directly write a vector SVG: beige squircle base, diagonally placed bamboo pen barrel, slanted nib, and a drop of ink from the tip.
- Use the project's existing Playwright Chromium (
scripts/render-icon.mjs) to render the SVG into a 1024Γ1024 transparent PNG. - Run
npx tauri iconto produce the macOS.icnsand all sizes at once. - The PM personally reviewed the 32px (Dock/small icon recognizability) and 512px previews before merging.
2. Table WYSIWYM (#59, P0): Design Assessment First, then Split into A/B Parallel Development
The original tables (#7) could render into HTML tables, but as soon as the mouse clicked in, the entire table reverted to | a | b | plain text source code, which was very jarring.
This requirement was large, so the PM split it into two sub-tasks with clear boundaries, assigned to kalamos-a and kalamos-b in parallel:
| Part | Responsible Pane | Content and Contract |
|---|---|---|
| Part A (#61) | kalamos-b |
Direct in-cell editing, updateDOM in-place updates, IME-safe write-back, keyboard navigation; Exports getActiveTableCell / focusTableCell for Part B to call |
| Part B (#62) | kalamos-a |
Cmd+Opt+T insert dialog (with grid picker), ` |
Part A: Let the coder assess the technical solution before starting
I particularly liked one action by the PM: before writing the first line of code in {% raw %}kalamos-b, it was asked to evaluate: "Should in-cell editing use contenteditable spans or a nested CodeMirror EditorView for each cell?"
The coder eventually chose contenteditable spans for very clear reasons:
- CodeMirror automatically ignores DOM mutations inside widgets, preventing interference.
- Native browser
contenteditablemakes CJK IME composition incredibly smooth; text is only written back to the underlying Markdown oncompositionend. - All editing and structural operations go directly through the main editor's history, integrating Undo/Redo naturally.
- A 10Γ5 table would require 50 nested
EditorViewinstances, which is too heavy for performance and memory.
Combined with updateDOM for in-place updates of non-focused cells, the entire table doesn't rebuild while typing, focus doesn't jump, and escapes for | β \| and newlines β <br> are handled correctly.
Part B: Pure function structural operations and shortcut conflicts caught by E2E
kalamos-a wrote all column/row insertion/deletion, alignment, and table deletion as table-ops.ts pure functions. Each operation is a single transaction (one Cmd+Z reverts the whole step). When writing back, it even calculates CJK full-width characters to auto-align the Markdown pipes.
A real-world episode occurred during development: the alignment shortcuts were initially set to Cmd+Opt+Shift+L / C / R. It turned out Cmd+Opt+Shift+R conflicted with the previously made "Clear Image Root" shortcut. Fortunately, the existing Playwright E2E tests caught this conflict immediately, and it was changed to the intuitive Cmd+Opt+Shift+β / β / β.
Three "Devils in the Details" caught during Review
The two PRs for tables (#61, #62) caught three issues during the Review phase that are classic examples of "things you wouldn't think of just looking at specs, but only expose during testing":
-
Typing
<br>literally in a cell became a newline: The PM wrote a round-trip test and found that if someone wanted to write the instructional text "<br>tag" in a table, it actually broke the line when saved and reloaded! This was fixed so literal<br>is saved as<br>. A boundary condition where "an odd number of\at the end of a cell escapes the pipe|" was also fixed by adding a space. - Row drag handles pushed the first column out of alignment: Originally, the row drag handle took up layout width, causing the first column's content to be indented relative to the header. This was changed to absolute positioning, appearing only on mouse hover, making the table's vertical alignment instantly clean.
- Floating toolbar covered the heading above the table: When clicking into a table, the toolbar floating above it pressed directly against the previous line's heading. The fix was to dynamically reserve 38px of space above the table when active and synchronize scroll compensation to prevent the screen from jumping or the active cell from shifting.
By the time the tables were merged, the project had accumulated 353 vitest and 137 e2e tests, and the input latency for a 10,000-line benchmark p95 was 17β18 ms, well below the 50 ms budget set in the PRD.
V. Doc Writer Online, Catching a CSS Bug via Screenshots (#63), and "Why Not Open Another Writer?"
With the features complete, it was time to prepare the "face" of the product: I opened an independent doc-writer Pane (running agy + Gemini 4 Neon, attached to the Kalamos.wt/docs worktree) and assigned four tasks:
- Rewrite the four-language README (English, Traditional Chinese, Japanese, Korean).
- Create the four-language static product page
site/(referencing Typora's whitespace and large screenshot rhythm, but with original text, colors, layout, and images). - Write a Playwright IPC mock script to capture screenshots directly from the rendered App.
- Add a GitHub Pages deployment workflow.
The PM reviewed two rounds and caught several flaws hidden in the details:
- The feature and shortcut tables in the README were cross-checked against the code one by one.
- In the HTML source code, newlines in the middle of Chinese sentences for layout caused an extra half-width space after CJK full-width punctuation in the browser; these were all cleaned up.
- The GitHub Pages workflow added
pathsfiltering to avoid redeploying the site every time the Rust code changed. - The hero screenshot on the homepage was changed to four versions (EN/ZH/JA/KO), so even the demo article in the screenshot changes with the language.
Unexpected Gain: Catching an App Layout Bug via Screenshots (#63)
The most interesting part was when doc-writer used Playwright to capture the first batch of App screenshotsβI immediately saw something wrong: the text in the editing area was flush against the left edge of the window, and the sidebar covered the text when opened!
But editor.css clearly had .cm-content { margin: 0 auto; }? Checking the DOM solved the mystery:
CodeMirror 6's base theme dynamically injects
.ΝΌ1 .cm-content { margin: 0; padding: 4px 0; }(CSS specificity0,2,0), and it injects later than our own stylesheet, overriding our.cm-contentwhich only had0,1,0!
The solution was clean: instead of using the ugly !important, I increased the selector specificity to 0,3,0 and ensured that when the sidebar is open, its width is subtracted from the outer container, allowing the paper column to center automatically in the remaining space:
/* .ΝΌ1 .cm-content (0,2,0) injected later overrides simple .cm-content */
/* Use 0,3,0 to beat CodeMirror base theme without !important */
.cm-editor .cm-scroller .cm-content {
width: 100%;
max-width: var(--k-max-width, 720px);
margin: 0 auto;
padding-block: 56px 120px;
padding-inline: var(--k-content-padding-x, 32px);
}
After PR #64 fixed this bug and added center-content.spec.ts, doc-writer re-captured all 9 images, and the interface immediately gained the "quiet piece of paper" vibe.
Management Decision: Should I open another Writer to share the load?
Writing four-language documentation and the product page took some time. Halfway through, I asked the PM: "Should we open a second writer to share the load?"
After assessment, the PM decisively said no, for very practical reasons:
- The work was entering the final stages.
- Two writers modifying the same set of README and
site/files simultaneously would only create massive merge conflicts. - A new writer would have to re-read the entire codebase; the cost of re-familiarization was higher than just letting the original one finish.
- The tone and terminology across the four languages would become inconsistent.
Multi-Agent collaboration isn't "the more Panes, the better." Parallelize only when you can cut clean interface boundaries (like Table Part A/B); highly coupled finishing work is faster with a single dedicated Agent.
VI. Pitfalls: PM Errors, Open Source Checks, macOS Signing, and Final Bugs Caught Writing Blogs
Entering the open-source and official packaging phase, a series of pitfalls emerged that you "absolutely won't encounter unless you walk the last mile."
Pitfall 1: PM's own errorβgh pr checks --watch disconnection fooled the merge gate
When merging Table Part A (#61), the PM followed the habit of using gh pr checks --watch to wait for GitHub Actions. Mid-way, a network connection reset occurred. --watch terminated early, and the PM didn't notice the CI was still running and clicked merge!
Although the main CI was green afterward and no disaster occurred, this was a process loophole. The PM changed habits on the spot: Never trust the exit code of --watch again; instead, use a loop with gh run view to explicitly check that status == completed and the conclusion is success before allowing a merge.
Pitfall 2: Transitioning from Private to Public Open Source and GitHub Pages
The repo was originally private. When preparing for GitHub Pages, we hit a GitHub free plan limit: private repos can't have Pages. The PM listed three options:
- Make the original repo public.
- Create a separate public repo just for the product page.
- Upgrade to GitHub Pro.
I chose to make the repo public. Before doing so, the PM scanned the entire git history (all 67 commits across branches):
- Confirmed no API tokens, keys, or certificates.
- Verified that test paths were fictional and didn't leak local environment info.
- The only thing I had to approve was that the commit author email would be public along with the history. I confirmed it was fine, made it public, added the MIT License (#66), and deployed the four-language product page via GitHub Actions.
Pitfall 3: v0.1.0 β v0.1.1 and the macOS ad-hoc signature "Damaged" crisis
The first time I installed the packaged Kalamos.app into /Applications, running codesign -v immediately threw an error:
code has no resources but signature indicates they must be present
With such an incomplete ad-hoc signature, when others download the .dmg, macOS might jump straight to "The application is damaged and cannot be opened," not even allowing a right-click to open. Therefore, before releasing the v0.1.0 pre-release, I added re-signing and re-packaging the .dmg to the release process:
codesign --force --deep -s - Kalamos.app
# Then use hdiutil to repackage into .dmg
When fixing #67 and #69 for the v0.1.1 release, I used the same re-signing process. After confirming it worked, I deleted the old v0.1.0 pre-release and set v0.1.1 as the Latest.
Pitfall 4: When opening an .md from Finder, Kalamos was greyed out (#67)
After dragging the app into /Applications, I tried right-clicking an .md file in Finder and selecting "Open With," but Kalamos was greyed out and unselectable!
There were two reasons:
-
tauri.conf.jsondidn't havefileAssociationsset, so the packagedInfo.plistlackedCFBundleDocumentTypesand the Markdown UTI declaration. macOS didn't know it could open.mdfiles. - Even if selectable, the Rust side hadn't handled the macOS
RunEvent::Openedevent, so double-clicking from Finder or cold-starting would result in nothing happening.
PR #68 fixed both: registered seven extensions (md, markdown, mdown, mkd, mkdn, mdwn, mdtxt) and the imported UTI net.daringfireball.markdown. When Rust receives an open event, if the frontend isn't initialized, it queues the event and processes it once the frontend is ready. Cold-starting with open -a Kalamos file.md was verified to work.
Pitfall 5: Using Kalamos to open "this blog" immediately caught broken ../images/ (#69)
The final bug felt particularly karmic. I finally used Kalamos to open the previous post on this blog (_posts/2026-11-15-herdr-review-queue-mod.md), and all ../images/xxx.png images showed "Failed to load image"!
The reason was that Tauri's asset protocol scope, for security, only allowed the folder where the document is located (i.e., _posts/). Jekyll blogs typically put posts in _posts/ and images in a parallel images/ folder. The path ../images/ was blocked.
But the fix couldn't be lazy by "allowing the entire parent folder" (if a user opens a file in their home directory, it exposes the whole folder to the WebView). PR #70 took a restrained approach:
- Added an
allow_asset_filecommand in Rust: usesfs::canonicalizeto resolve..and symlinks, confirms it's a real file, and checks if the extension is in the image whitelist. - After passing checks, only that specific image file is added to the
asset_protocol_scope, never the entire parent folder. - Before the frontend loads a local image not in the document directory, it calls
allow_asset_file(with caching and a retry on failure).
#[tauri::command]
pub fn allow_asset_file(app: tauri::AppHandle, path: String) -> Result<(), AppError> {
use tauri::Manager;
let requested = Path::new(&path);
let canonical = check_asset_file(requested)?; // canonicalize + file check + image extension whitelist
let scope = app.asset_protocol_scope();
let to_err = |e: tauri::Error| AppError::new(crate::error::ErrorKind::Io, e.to_string());
scope.allow_file(&canonical).map_err(to_err)?;
if requested != canonical {
scope.allow_file(requested).map_err(to_err)?;
}
Ok(())
}
After the fix, the PM verified it using the packaged App with the same _posts/ + ../images/ structure. Images loaded successfully, and I finally felt safe cutting the official v0.1.1 release.
VII. Final Acceptance Numbers and the Multi-Agent Collaboration Checklist Learned This Time
As of v0.1.1 (latest main), all automated defenses and benchmarks are green:
| Check Item | Result | Description |
|---|---|---|
| Vitest Unit Tests | 369 passed | Covers parser, table-ops, positions, export, image logic |
| Playwright E2E | 145 passed | Includes real keyboard typing, tables, centering, IME stress tests |
Rust cargo test |
86 passed | Atomic saves, file association queue, asset scope whitelist, and symlink protection |
| Rust Clippy | 0 warnings | cargo clippy --all-targets -- -D warnings |
| GitHub Actions CI | All Green (macos-latest) |
Auto-runs tsc / vitest / build / cargo test / clippy / Playwright on every PR |
| Input Latency p95 | 17β18 ms | 10,000-line long text benchmark, far below the 50 ms goal |
I've summarized the experience of running a large project over these three days into an advanced Herdr Collaboration Checklist:
- [ ] 1. Let the coder do a design assessment before writing code for complex features: Like comparing
contenteditablevs. nestedEditorViewfor tables, saving the cost of going down the wrong path. - [ ] 2. Split large requirements into "Interface Contract + Dual Worktree Parallelism": Part A exports
getActiveTableCell/focusTableCell, allowing Part B to start simultaneously with almost zero merge conflicts. - [ ] 3. No need to stop when the quota is exhausted; switch models in the same worktree: When agy hit
Individual quota reached, I immediately switched toclaude --permission-mode autoto take over. - [ ] 4. Don't force a second Agent for finishing work: For highly coupled tasks like translation and product page finishing, a single dedicated writer is faster and more consistent in tone.
- [ ] 5. Don't just trust
gh pr checks --watch: Network interruptions can cause it to end early. Usegh run viewto explicitly checkstatus == completedbefore merging. - [ ] 6. Close the Pane when the task is merged: Develop the habit of using
hc kill+hc rmto keep the Herdr window from being cluttered with idle terminals. - [ ] 7. Write a "fails on old code" regression test before fixing a bug: Like the IME out-of-bounds in #56 and the
<br>round-trip in #59; it's only fixed when it turns from red to green. - [ ] 8. Screenshots and "opening your own real project" are the strongest acceptance tests: Screenshots caught the CSS specificity issue in #63; opening my own blog caught #67 and #69.
- [ ] 9. Always check
codesignandInfo.plistbefore a macOS release: Verify the ad-hoc signature is complete and that file association UTIs andRunEvent::Openedare all connected.
Summary
Looking back at the evolution of these four Herdr practical articles, it's quite interesting:
-
From fixing bugs to building a complete product: The first article fixed an existing backend, the second made a small tool, the third wrote a mod for the workflow, and the fourth took a complete desktop editor PRD (M1βM3) from zero to MIT open source and
v0.1.1in three days. - Models are just slots; the process is the asset: When the agy quota ran out halfway through development, switching to Claude Code in the same worktree allowed for a seamless continuation. As long as the specs, contracts, tests, and git discipline are in the PM's hands, any model can take over.
- Beyond "all tests passed," you always need a real user's hands: If I hadn't typed personally, hadn't asked doc-writer to take screenshots, and hadn't used it to open the previous post on this blog, the issues in #49, #54, #63, #67, and #69βwhich most affect the user experienceβwould never have been caught by CI alone.
-
The tool is finally back in my hands: Kalamos can now open the
.mdfiles of this blog directly from Finder and correctly load screenshots from../images/. From now on, I can write articles using the editor I built together with the Agents.
Feel free to download and try it out, or visit the repo to browse or give it a star:
- GitHub Repo: kkdai/Kalamos
- Product Page: https://kkdai.github.io/Kalamos/
- Official Release Download: Release v0.1.1
Previous articles in this series:
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.




