VOOZH about

URL: https://dev.to/the7thfreedom/i-ported-a-macos-only-ai-agent-tool-to-windows-heres-what-i-learned-1g1c

⇱ I ported a macOS-only AI agent tool to Windows — here's what I learned - DEV Community


I've been experimenting with multi-agent coding workflows for a
while now — running Claude Code, Codex, and Cursor in parallel,
each agent working on its own isolated branch. It's a genuinely
different way to develop once you get it working.

The best tool I found for orchestrating this is
Superset by superset-sh. It lets you spin
up multiple CLI-based coding agents across isolated git worktrees,
direct their work from a single interface, and merge results when
done. Clean, fast, well-built.

One problem: macOS only.

I'm on Windows. So I did what any mildly stubborn developer would
do — I ported it.


What Superset actually does

Before getting into the port, it's worth explaining why I thought
it was worth the effort.

The core idea is parallel agent execution across git worktrees.

Instead of:

You → one agent → one branch → wait → review → repeat

You get:

You → agent A (feature-1 worktree)
 → agent B (feature-2 worktree) 
 → agent C (bugfix worktree)
 → all running simultaneously

Each agent has its own working directory, its own branch, no
shared state. You review and merge when ready. For the right
kind of tasks, it's a significant productivity shift.


Why the Windows port was non-trivial

This wasn't a simple config change. A few things needed real work:

1. Terminal: macOS pty → Windows ConPTY

The original uses node-pty, which works great on macOS/Linux but
has historically been painful on Windows. I switched to
Windows ConPTY — the modern Windows pseudo-terminal API
that's been available since Windows 10 1809.

// macOS: node-pty
const pty = spawn('bash', [], { 
 name: 'xterm-color',
 env: process.env 
})

// Windows: ConPTY via node-pty with Windows-specific flags
const pty = spawn('powershell.exe', [], {
 name: 'xterm-color',
 useConpty: true,
 env: process.env
})

ConPTY is solid now. The main gotcha is that some ANSI escape
sequences behave slightly differently — took some time to
normalize the output rendering.

2. File paths: backslashes everywhere

Windows uses backslashes. The codebase assumed forward slashes
throughout — in worktree paths, git commands, config files,
log output, everything.

The fix wasn't hard but it was tedious: normalize all internal
paths to forward slashes, then convert at the system boundary
only when actually calling Windows APIs.

// Normalize on input
const normalize = (p: string) => p.replace(/\\/g, '/')

// Convert back only when calling Windows shell
const toWin32 = (p: string) => p.replace(/\//g, '\\')

3. Shell integration: PowerShell / cmd / WSL

On macOS, you assume bash or zsh. On Windows, you need to handle:

  • PowerShell 7+ (recommended)
  • cmd.exe (legacy fallback)
  • WSL (Linux environment on Windows)

Each has different ways to set environment variables, run
scripts, and handle exit codes. I ended up with a shell adapter
layer that normalizes the interface across all three.

4. Build pipeline: dmg → nsis/msi

The upstream build targets macOS .dmg. For Windows I switched
the Electron-builder config to target:

  • NSIS installer (.exe) — standard Windows installer with install/uninstall support
  • MSI — for enterprise environments
// electron-builder.ts (Windows targets)
win: {
 target: [
 { target: 'nsis', arch: ['x64'] },
 { target: 'msi', arch: ['x64'] }
 ]
}

5. Keyboard shortcuts: ⌘ → Ctrl

Every keyboard shortcut in the UI used macOS modifiers. Went
through the entire shortcut map and remapped:

  • Ctrl
  • Alt
  • ⌘⇧Ctrl+Shift

Small thing, but important for it to feel native on Windows.


What I notified upstream

I opened an issue with the superset-sh team
(superset-sh/superset#5011)
to let them know about the port. SuperWin maintains the same
Elastic License 2.0 as upstream and aims to stay rebased
on upstream main.

This is an unofficial community port — not affiliated with or
endorsed by the superset-sh team. If they ever ship an official
Windows build, great. Until then, SuperWin exists.


Current state

  • ✅ Runs on Windows 10 (1809+) and Windows 11
  • ✅ PowerShell / cmd / WSL support
  • ✅ Claude Code, Codex, Cursor orchestration working
  • ✅ Isolated git worktree management
  • ⏳ No prebuilt installer yet — build from source for now
  • ⏳ Installer coming in a future release

Requirements:

  • Bun v1.0+ for Windows
  • Git for Windows 2.40+
  • PowerShell 7+ (recommended)

Try it

git clone https://github.com/the7thfreedom/superwin.git
cd superwin
Copy-Item .env.example .env
bun install
bun run dev

GitHub: the7thfreedom/superwin


What I'd do differently

If I were starting over:

  1. Start with ConPTY from day one — I spent too long trying to make node-pty work before switching
  2. Path normalization layer first — add it as a utility module before touching anything else
  3. Test on WSL earlier — WSL path handling is its own category of edge cases

If you're a Windows developer doing AI-assisted coding and
have been watching the agent orchestration space from the
sidelines — this is your on-ramp.

Questions, feedback, bug reports all welcome. What's your
current AI coding workflow on Windows?