Worktrees and tmux

WTmag uses two things you might already use every day: git worktrees and tmux. The combination is deliberate — it's what makes workers inspectable instead of opaque background processes.

Worktrees

Each worker gets its own checkout. Separate files, separate branch state, separate everything. Two agents can work at once without overwriting each other's changes or fighting over the working directory. No merge conflicts with yourself.

WTmag uses WorkTrunk to manage worktrees. A worker from issue 456 gets a worktree named something like github-issue-456. WorkTrunk hooks can reuse ignored files and caches to reduce cold starts, so the worktree feels less like a fresh clone and more like a workspace you've been in before.

tmux

Workers run in tmux, not as headless background processes. That means you can attach to them, read what the agent is doing, split a pane to run tests, or stop the whole thing and take over. The agent is running in a normal terminal environment — you just happen to be sharing it.

This is the core design choice. The worker is not a black box. It's a tmux session you can walk into at any point.

Windows vs sessions

WTmag can open a worker as a window in your current tmux session, or as its own session.

Windows are the default. They're lightweight — one extra tab in tmux. Good for most tasks, and they keep everything in one place so you can switch with a keystroke.

Sessions are heavier but give the worker its own tmux lifecycle. Useful when a task grows and needs more panes, more windows, or just some breathing room.

Switch for one run:

wtmag create --github 456 -t issue -s   # dedicated session
wtmag create --github 456 -t issue -w   # window in current session

Or promote later when a window worker outgrows its space:

wtmag promote --id project-github-issue-456

Windows require being inside tmux already. Sessions don't.