Architecture

Process Model

ZigShell is a native Win32 app written in Zig. It hosts real Windows console windows instead of rendering terminal text itself.

ZigShell.exe
  ├─ custom Win32 sidebar and overlays
  ├─ reparented cmd.exe / powershell / ssh windows
  ├─ optional owned Edge windows
  └─ notification and zsb bridge listeners

Shell Hosting

Each shell is a real console process. ZigShell finds or spawns the console window, strips unwanted window styles, reparents it into the right pane, and moves it during layout changes.

This keeps memory low and avoids terminal rendering complexity.

Native Browser Pane

Browser panes are native Edge windows owned and positioned by ZigShell. They are not WebViews. This preserves full browser features but requires careful geometry, focus, and mask handling.

Notifications

ZigShell listens on local notification ports and receives messages such as:

ACTIVE:<session>
DONE:<session>
TITLE:<session>:<subject>
SESSION:<session>:<claude-session-id>:<cwd>
AGENT:<session>:<kind>
OPENBROWSER:<shell-id>:<url>
SIDEBAR:<shell-id>

Remote VPS sessions reach the local listener through SSH reverse tunnels.

Workspace Persistence

Session state is stored in JSON files under %APPDATA%\ZigShell. Workspace display names live in windows.json; shell state lives in session files.

Runtime-only state should not be persisted:

• spinner activity
• blue dots
• transient focus state
• temporary browser launch/adopt state

Persisted state should include:

• shell kind
• visible name and naming source
• tmux session id
• workspace id
• browser URL and enabled state
• last active ordering metadata

DEV vs Stable

Stable and DEV are separate binaries and use separate session files. DEV should be used for risky UI and geometry changes until screenshots and state checks prove the behavior.