Prequel
When writing blog posts or replying to Issues, I often need to record a short clip of screen operations. The built-in QuickTime (or ⌘⇧5) in macOS records in .mov format, which always requires using another tool to convert to GIF and adjust dimensions, which is very troublesome.
So I wanted a very simple tool:
An interface like QuickTime's "New Screen Recording" that can record the entire desktop or a selected area, directly generate a GIF after recording, and allow choosing the GIF resolution.
Coincidentally, I used Herdr for the first time and it went very smoothly, so this time I decided to scale up the experiment:
- Claude Code as PM: Create remote GitHub repo, write SPEC, open Issues, review, commit, and push.
- agy as coder, with two Panes open at once: Solve two Issues simultaneously.
- Each coder must report back to Claude Code upon completion; commits are only made after the review passes.
The result is here: kkdai/record2gif. It took about one day from creating the repo to successfully saving a GIF to the desktop.
I. What does record2gif do?
| Feature | Description |
|---|---|
| QuickTime-style Control Bar | A small floating window: Record Entire Screen / Record Selection, Options, Red Record button |
| Selection Area | Full-screen semi-transparent mask, drag a box, displays pixel dimensions, can be adjusted before recording |
| During Recording | Control bar automatically hides (won't be recorded), menu bar displays ⏹ + mm:ss, click or press ⌃⌘Esc to stop |
| Export Window | Looping preview, Resolution (Original / 1280 / 960 / 640 / 480 / 320 px / Custom width, maintains aspect ratio, never upscales), Frame Rate (5–30 fps), Infinite Loop toggle, estimated output size |
| Saving | Defaults to Desktop, filename Recording 2026-11-14 at 15.13.43.gif, includes progress bar, can be canceled, can show in Finder after saving |
Technical choices were intentionally kept simple, with absolutely no third-party packages:
| Component | Technology |
|---|---|
| Project | Swift Package Manager (no .xcodeproj), macOS 14+ |
| UI | SwiftUI + AppKit (NSPanel, NSStatusItem, mask window) |
| Recording | ScreenCaptureKit (SCStream) → AVAssetWriter writing H.264 .mov temporary file |
| GIF Conversion | AVAssetReader frame-by-frame decoding + ImageIO (CGImageDestination) encoding |
| Global Shortcut | Carbon RegisterEventHotKey (no accessibility permissions required) |
| Testing | Swift Testing, 19 tests |
Recording is always done at native pixel resolution (points × scale). Downscaling only happens during GIF export, so the same recording can be exported in multiple sizes.
II. PM's Job: Write the SPEC first, then break down Issues
When two coders write code in parallel, the biggest fear is "each writing their own way, and failing to integrate at the end." Therefore, the first thing Claude Code did was not to start the coders, but to write a SPEC.md. The two most important things in it were:
- Fixed Directory Structure: Which Issue can only modify which folder (e.g., only #4 can modify
Recording/, only #5 can modifyExport/). - Interface Contract between Issues: Write the public APIs for
ScreenRecorder,GIFExporter, andGIFSizingdirectly into the SPEC first.
public final class GIFExporter: Sendable { public init() public func export(video: URL, to output: URL, options: GIFExportOptions, progress: @escaping @Sendable (Double) -> Void) async throws } With the contract in place, the coder working on the UI doesn't need to wait for the recording engine to be finished to know what to call.
Then it was broken down into 5 Issues, divided into three rounds:
| # | Issue | Dependency | Round |
|---|---|---|---|
| 1 | Project skeleton, App shell, build script | – | Round 1 |
| 2 | ScreenCaptureKit recording engine | 1 | Round 2 (Pane A) |
| 3 | GIF Export (Resolution / fps) | 1 | Round 2 (Pane B) |
| 4 | QuickTime-style recording UI | 1, 2 | Round 3 (Pane A) |
| 5 | Export window: Resolution selection, preview, saving | 1, 3 | Round 3 (Pane B) |
III. Parallel Development with Two agy Panes
1. One git worktree per coder
If two agy instances modify files in the same folder at the same time, they will definitely clash. Therefore, a separate git worktree / branch was opened for each Issue, and coders only worked within their own worktree:
git worktree add ../record2gif-wt/issue-2 -b issue-2 git worktree add ../record2gif-wt/issue-3 -b issue-3 2. Opening coder Panes
The agy startup method learned from the previous post was reused:
hc run --bg --outlive-parent --name coder-a --cwd ../record2gif-wt/issue-2 \ agy --dangerously-skip-permissions -i "$TASK" herdr-app do terminal.keep --terminal <ID> --place right # First one on the right herdr-app do terminal.keep --terminal <ID> --place down # Second one stacked below The screen then looked like this: Claude Code (PM) on the left, and two agy coders on the right (top and bottom).
A few small changes this time:
| Item | Description |
|---|---|
-i | agy "prompt" will exit 2 directly; use agy -i "..." instead |
--dangerously-skip-permissions | In the last post, I wrote a driver script to authorize permissions one by one; this time, coders are confined to their own worktrees and cannot commit/push, so I chose to skip permissions directly to avoid the Panes getting stuck on permission dialogs |
| Trust Dialog | Opening agy in a new folder for the first time still asks for trust; handled with hc keys <t> enter |
| Waiting for Reports | hc wait --children any: Review whichever coder finishes first |
3. Review Process
sequenceDiagram participant PM as Claude Code (PM) participant A as agy Pane A participant B as agy Pane B participant GH as GitHub PM->>A: Issue #2 + SPEC path + worktree PM->>B: Issue #3 + SPEC path + worktree par Parallel Implementation A->>A: Implement + swift build + swift test and B->>B: Implement + swift build + swift test end B->>PM: hc send: Completed #3 PM->>PM: git diff, swift test, check against SPEC PM->>B: Feedback (if any) A->>PM: hc send: Completed #2 PM->>GH: Merge to main, commit, close Issue The benefit of hc wait --children any is that while A is still writing, the PM can review B first without them blocking each other.
IV. The real work begins after make run
All 5 Issues were merged, all 19 tests passed, and make app successfully packaged build/record2gif.app. However, when I actually ran it:
| # | Symptom | Root Cause |
|---|---|---|
| 6 | Control bar window became a 900×450 large white frame | Default SwiftUI Window size |
| 7 | Clicking Record makes the App disappear | The last window was hidden, and SwiftUI automatically terminated the App |
| 8 | Screen recording permissions don't work no matter what | Ad-hoc signature changes with every build |
| 9 | No seconds displayed in the menu bar during recording | Race condition in object connection order |
| 10 | GIF export failed | Screen recording produces Variable Frame Rate video |
Passing all tests is a far cry from "actually working." These 5 bugs were also opened as Issues, assigned to coders to fix, and reviewed by the PM. Let's go through them one by one.
Bug #6: Control bar became 900×450
If a SwiftUI Window scene isn't specifically configured, it gives a default size. For a small control bar like QuickTime's, you need to add:
Window("record2gif", id: "main") { ... } .windowResizability(.contentSize) This makes the window fit the content size.
Bug #7: Clicking Record "crashes" the App
I initially thought it was a crash, but there were no .ips files in ~/Library/Logs/DiagnosticReports. Checking the unified log revealed the App was terminating normally on its own.
Pro tip: In my zsh,
logis overridden by the shell; use/usr/bin/log show --predicate 'process == "Record2Gif"'.
The reason: During recording, the control bar must be hidden (so it isn't recorded), and a SwiftUI App with only one Window will automatically terminate when the last window disappears. The fix is to disable this behavior in the AppDelegate:
func applicationShouldTerminateAfterLastWindowClosed(_ sender: NSApplication) -> Bool { false } This trap was actually set by the PM: during the review of #4, Claude Code asked the coder to change WindowGroup to a single Window (to avoid opening multiple control bars), but didn't anticipate this side effect.
Bug #8: Screen recording permissions are useless
This was the most annoying part of the project. After enabling record2gif in "System Settings → Privacy & Security → Screen Recording," permissions were lost again after a rebuild.
The reason: macOS TCC permissions are tied to the App's code signature (Designated Requirement). Initially, the build script used ad-hoc signing (codesign -s -), so the CDHash changed with every build, and macOS treated it as a "different App."
The solution is to create a locally self-signed code signing certificate. If scripts/build-app.sh finds it, it uses it for signing:
# Only needs to be done once per machine; full instructions in README # cert.conf sets CN = record2gif Local Signing, extendedKeyUsage = codeSigning openssl req -x509 -newkey rsa:2048 -nodes -days 3650 -config cert.conf ... openssl pkcs12 -export -legacy ... -out cert.p12 security import cert.p12 -k ~/Library/Keychains/login.keychain-db -T /usr/bin/codesign # Clear old ad-hoc records, repackage, authorize once tccutil reset ScreenCapture com.kkdai.record2gif make app && open build/record2gif.app After this, the Designated Requirement is fixed to identifier "com.kkdai.record2gif" and certificate leaf = H"...", and permissions persist through rebuilds. The build script also prints the codesign -dr - result for easy verification.
Bug #9: No seconds in the menu bar
During recording, the menu bar should display the elapsed time like ⏹ 00:12. The code seemed correct, but it wouldn't appear.
The cause was the connection order of two objects in the AppDelegate: AppModel would notify StatusItemController when the recording state changed, but at the moment of notification, statusItemController hadn't been set yet, so the message was dropped. The fix was to connect them in the didSet of both sides, ensuring they connect regardless of which is created first, and making the didSet of phase and recorder.$elapsed the sole sources for updating the menu bar.
Bug #10: GIF export failed
The final hurdle: after recording and clicking Save GIF, an error popped up:
GIF export failed: The operation couldn't be completed. (Record2GifCore.GIFExportError error 1.) First, a complaint about the error message: error 1 is completely meaningless to the user, so I had GIFExportError implement LocalizedError to provide readable messages.
The real reason: ScreenCaptureKit records Variable Frame Rate (VFR) video. When the screen doesn't change, it doesn't send new frames, so the timestamps are irregular. The original method used AVAssetImageGenerator.images(for:) to request a batch of frames at fixed time points, which fails with VFR video.
I changed it to use AVAssetReader to decode sequentially from start to finish. For each GIF time point t = i / fps, it takes the "last frame where timestamp ≤ t":
flowchart LR V["VFR .mov<br/>Irregular frame timing"] --> R["AVAssetReader<br/>Sequential BGRA decoding"] R --> P{"For each GIF time t = i/fps<br/>Take last frame with PTS ≤ t"} P --> S["Scale to selected resolution<br/>(No upscaling, even dimensions)"] S --> G["CGImageDestination<br/>Write to GIF"] This way, regardless of how irregular the original video frames are, the output GIF has a fixed frame rate. I also added tests for VFR.
This trap was also set by the PM: during the review of #3, Claude Code suggested the coder switch to the batch images(for:) API. Since the test videos at the time were all constant frame rate, the tests passed.
After the fix: "It works! GIF successfully saved to desktop." 🎉
V. PMs make mistakes too
Looking back at these 10 Issues, two bugs (#7, #10) were actually caused by modification suggestions made by the PM during review. This is worth noting:
- Reviewer suggestions also need verification. The previous post said "Reviewer conclusions must also be reviewed"; this time it's the opposite: modifications proposed by the Reviewer can introduce bugs.
- Unit tests cannot catch these two types of problems. App lifecycle (closing the last window) and the characteristics of real recording files (VFR) can only be discovered by actually running the app.
- Humans must test it once. All 5 of these bugs were discovered during my actual operation. No matter how careful the review between Agents is, it cannot replace manual testing.
VI. Parallel Multi-Agent Development Checklist
- 1. Write the SPEC first and lock down the interface contract: public APIs, directory structure, which Issue can modify which folder.
- 2. Divide rounds by dependency: Issues in the same round must not depend on each other.
- 3. One git worktree per coder: Avoid modifying the same folder simultaneously.
- 4. Coders do not commit or push: Handled uniformly by the PM after review. This is also the prerequisite for safely using
--dangerously-skip-permissions. - 5.
hc wait --children any: Review whoever finishes first. - 6. After all tests pass, you must package and operate the app manually.
- 7. For macOS Apps requiring permissions, handle signing on day one: Otherwise, you'll have to re-authorize after every rebuild.
- 8. Error types should implement
LocalizedError: Otherwise, users will only seeerror 1. - 9. Reviewer suggestions can be a source of bugs: Especially suggestions involving framework behavior (App lifecycle, video formats).
Summary
- SPEC + Interface Contract is the key to parallel development: Two agy Panes wrote the recording engine and GIF export simultaneously, and there were almost no conflicts during merging.
- Herdr makes "one PM, two coders" visible: You can see the PM assigning tasks and reviewing on the left, and what the two coders are doing on the right in real-time.
- "Tests passed" is just the beginning: 5 bugs appeared only when actually running the app, 2 of which were planted by the PM during review.
- macOS Nuances: Screen recording permissions are tied to code signatures, SwiftUI Apps with one window terminate themselves, and ScreenCaptureKit outputs VFR.
record2gif is now open source at kkdai/record2gif. You can package it yourself with make app. From now on, I'll probably use it to record all the operation GIFs for my blog.
![[Herdr in Action] Parallel Development with Two Panes: Building record2gif in One Day](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fejvrrvknc22sio4jdau8.png)

