Your First Session

This walkthrough takes you from zero to a working gwt session.

1. Attach to a session

gwt attach --all

This starts a Zellij session named gwt (configurable via session.name) and creates tabs for all worktrees. You’ll see:

• Tabs at the top — one per worktree attached to this session
• Left pane — AI chat agent
• Top-right pane — gateway dashboard
• Bottom-right pane — shell

2. Create a feature branch

From within the session, create a new worktree:

gwt create feat/my-feature

This creates a worktree at .worktrees/feat-my-feature/ and adds a new tab to your session.

3. Switch to it

gwt switch feat/my-feature

The Zellij tab switches automatically. You’re now working in the new worktree.

4. Start the gateway

If you have gateway apps configured:

gwt gateway start

Your apps are now available at subdomain URLs:

  gwt gateway running on http://localhost:54846

    http://frontend.localhost:54846  ->  :3001
    http://diff.localhost:54846      ->  :3002

5. Work on your feature

Write code, commit as usual. The worktree is a normal git checkout — all git commands work as expected.

6. Review your changes

If Diffity is available:

gwt diff

This opens a browser-based diff view where you can leave comments and have AI process them.

7. Merge when ready

gwt merge

This runs the full pipeline:

1. Verify — runs pre-merge hooks
2. Rebase — rebases onto the target branch
3. Squash — combines commits into one with an AI-generated message
4. Merge — fast-forward merges into the target branch
5. Cleanup — removes the worktree and branch

8. Detach when done

To close the current workspace tab:

gwt detach

To close all tabs for this repo:

gwt detach --all

To leave the session running in the background (processes keep running), press Ctrl+Q inside Zellij.