Kalamos Multi-Agent Collaborative Development Architecture: Human and Claude Code PM on the left, multiple independent Herdr worktree Panes on the right, GitHub Actions CI and release pipeline below

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:

Kalamos Traditional Chinese Real-time Preview (Papyros Papyrus Light Theme)

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)

Offline real-time rendering of MathJax formulas and Mermaid flowcharts

Melan Dark Theme and Custom CSS Variable Example

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:

  1. 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).
  2. 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, using hc send / hc wait for asynchronous task assignment and reporting.
  3. 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 executes hc kill + hc rm to 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**, code render 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:

  1. Directly write a vector SVG: beige squircle base, diagonally placed bamboo pen barrel, slanted nib, and a drop of ink from the tip.
  2. Use the project's existing Playwright Chromium (scripts/render-icon.mjs) to render the SVG into a 1024×1024 transparent PNG.
  3. Run npx tauri icon to produce the macOS .icns and all sizes at once.
  4. The PM personally reviewed the 32px (Dock/small icon recognizability) and 512px previews before merging.

Kalamos Reed Pen App Icon (beige squircle, diagonal bamboo barrel, and a drop of ink)

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:

  1. CodeMirror automatically ignores DOM mutations inside widgets, preventing interference.
  2. Native browser contenteditable makes CJK IME composition incredibly smooth; text is only written back to the underlying Markdown on compositionend.
  3. All editing and structural operations go directly through the main editor's history, integrating Undo/Redo naturally.
  4. A 10×5 table would require 50 nested EditorView instances, 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":

  1. 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 &lt;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.
  2. 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.
  3. 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.

Kalamos Visual Table Editing: Direct in-cell editing, floating toolbar that doesn't block text, and auto-alignment

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 paths filtering 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 specificity 0,2,0), and it injects later than our own stylesheet, overriding our .cm-content which only had 0,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:

  1. The work was entering the final stages.
  2. Two writers modifying the same set of README and site/ files simultaneously would only create massive merge conflicts.
  3. 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.
  4. 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:

  1. Make the original repo public.
  2. Create a separate public repo just for the product page.
  3. 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:

  1. tauri.conf.json didn't have fileAssociations set, so the packaged Info.plist lacked CFBundleDocumentTypes and the Markdown UTI declaration. macOS didn't know it could open .md files.
  2. Even if selectable, the Rust side hadn't handled the macOS RunEvent::Opened event, 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:

  1. Added an allow_asset_file command in Rust: uses fs::canonicalize to resolve .. and symlinks, confirms it's a real file, and checks if the extension is in the image whitelist.
  2. After passing checks, only that specific image file is added to the asset_protocol_scope, never the entire parent folder.
  3. 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 contenteditable vs. nested EditorView for 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 to claude --permission-mode auto to 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. Use gh run view to explicitly check status == completed before merging.
  • [ ] 6. Close the Pane when the task is merged: Develop the habit of using hc kill + hc rm to 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 codesign and Info.plist before a macOS release: Verify the ad-hoc signature is complete and that file association UTIs and RunEvent::Opened are all connected.

Summary

Looking back at the evolution of these four Herdr practical articles, it's quite interesting:

  1. 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.1 in three days.
  2. 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.
  3. 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.
  4. The tool is finally back in my hands: Kalamos can now open the .md files 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:

Previous articles in this series: