Repository navigation
v0.8.1 — Desktop App & Integrated Terminals
Forge is now a standalone desktop app. Download the installer, sign in, and you're running — no Node.js, no terminal, no setup. This release also adds integrated terminals, smarter stall detection, persistent unread counters, and manager renaming.
Desktop App
Forge ships as a native desktop application for macOS and Windows, built with Electron. Everything is bundled — backend, UI, and all dependencies — into a single installer.
- One-click install — DMG for macOS (signed + notarized), NSIS installer for Windows
- Bundled backend — esbuild-bundled backend reduces 55,000 files to 127, with native modules staged automatically
- Auto-update —
electron-updaterchecks for new releases every 2 hours with time-of-day gating; manual check available in the app menu. Blocks restart when sessions are active. - What's New dialog — shown after updates with release highlights
- LAN/Tailscale ready — binds to
0.0.0.0by default for remote access from mobile devices - External links — open in your system browser, not an in-app window
- Dark mode by default — native theme detection with platform-appropriate window chrome
- macOS —
hiddenInsettitle bar with traffic light integration - Windows — native title bar with auto-hidden menu bar, proper
node-ptysupport - App icon — clean icon matching the mobile app, with
.icnsand.icovariants - Runtime lock hardening — stale PID detection, same-PID reclaim, emergency release on exit to prevent leftover lock files after crashes
- CI pipeline — GitHub Actions builds for Windows; macOS builds locally with Apple signing
Integrated Terminals
Per-session terminals backed by node-pty (backend) and xterm.js (frontend). Open a terminal right inside Forge — no switching to a separate app.
- Full PTY — cross-platform shell spawning (macOS/Linux default shell, Windows ConPTY)
- Persistence — periodic VT state snapshots + output journal; terminals restore across server restarts with full scrollback
- Session scoped — terminals belong to a manager session and are cleaned up on session delete. Sidebar shows terminal count badge.
- Bottom panel UI — tabs-only, open, and maximized modes with drag-to-resize
- WebGL rendering — lazy-loaded xterm.js with WebGL acceleration
- Dedicated WebSocket — raw binary I/O on a separate connection with ticket-based auth
- 51 tests covering persistence, PTY runtime, service lifecycle, access policy, and output batching
Worker Stall Detection
Upgraded from two-stage to three-stage escalation with detailed context at each step.
- Stage 1 (5 min) — light nudge to the manager
- Stage 2 (10 min, repeats every 10 min) — detailed report with the tool name, truncated command input, last output, and elapsed time so the manager can decide whether to intervene or let it run
- Stage 3 (30 min) — automatic termination (raised from the previous 10-min threshold)
Persistent Unread Counters
Unread message counts now survive server restarts and work correctly across multiple tabs.
- Server-authoritative — counts tracked in
unread-state.jsonper profile with debounced atomic writes - Bootstrap snapshot —
unread_counts_snapshotsent on connect so counts are correct immediately - Auto-increment — counts bump on
speak_to_userandchoice_requestevents - Mark-read on subscribe — switching to a session clears its count
- Shutdown flush — pending writes are flushed before exit
- Mark unread — mark sessions as unread from the sidebar with immediate badge update
Rename Managers
Right-click any manager profile in the sidebar and select "Rename" to give it a custom display name. The rename is cosmetic only (data directories and internal IDs are unchanged) and syncs instantly across all connected clients.
Fixes
- SSR guard —
window.electronBridgeaccess guarded for server-side rendering - TanStack devtools — disabled in Electron to avoid Shift+A keyboard conflict