Sessions & Workspaces

Session Identity

Each tab has a visible title and, for tmux-backed tabs, a tmux session id. Use the visible title when talking to humans. Use the tmux id when debugging routing.

Example:

Visible title: fix the big bad query
tmux id:       hypertasks-50

Naming Hierarchy

ZigShell should prefer the highest-confidence name:

1. Manual ZigShell rename with F2 or double-click.
2. Explicit agent/session rename when the underlying Claude Code session changes its name.
3. Dynamic Claude/tmux title.
4. Current working directory or fallback shell title.

Manual ZigShell renames are sticky. Clearing the name should allow automatic naming again.

Workspaces

Workspaces are persistent top-level ZigShell windows or in-process workspace slots. User-facing workspace names are stored separately from stable workspace ids.

Important files:

• %APPDATA%\ZigShell\windows.json
• %APPDATA%\ZigShell\session.json
• %APPDATA%\ZigShell\session-{workspace-id}.json

Closing a workspace should not delete its sessions. It should mark that window as not restoring on next startup while keeping it available from the workspace history.

Moving Shells

Shells can be moved into open or remembered closed workspaces. Moving a shell should preserve:

• visible title
• tmux session id
• browser pane URL state
• zsb binding, or enough metadata to rebuild it
• last activity ordering metadata

Sort Order

The sidebar should promote sessions by useful attention:

1. Priority or pinned/current special state if present.
2. Active spinner sessions.
3. Needs-input blue-dot sessions.
4. Recently used idle sessions.
5. Older idle sessions.

Muted tabs must not stay pinned because of activity.