Your First Worker

You've installed WTmag and you're inside a tmux session in your project worktree. Here's what a real first run looks like — not just the commands, but the flow.

Start your orchestrator

Default config opens workers as tmux windows in your current session, so you need to be inside tmux first:

tmux new -s project-dev

Load the WTmag skill into your agent and start talking:

pi --skill ./skill

You're now in a conversation with your orchestrator. You can talk naturally about what needs doing.

Dispatch a worker

The simplest way is to just tell your orchestrator what to work on. You can reference a GitHub issue by number:

Fix the login bug in issue 456

Your orchestrator understands the intent and runs the command for you:

wtmag create --github 456 -t issue

WTmag fetches the issue with gh, creates an isolated worktree, writes .wtmag/prompt.md with the full brief, opens a tmux window, and starts the default agent inside. The worker runs in the background. The orchestrator tells you how to attach.

You can also run the command directly, without the orchestrator:

wtmag create --github 456 -t issue

Both paths do the same thing. The orchestrator just saves you the context switch.

See what's running

wtmag list

Across all projects:

wtmag list --all

Jump in

The whole point of WTmag is that workers are real tmux sessions you can see and touch. You have a few ways to get to one:

tmux-sessionx (recommended): press your prefix and f, fuzzy-find the worker by name, and you're in.

Direct attach:

wtmag attach project-github-issue-456

Or just switch tmux windows manually. It's just tmux.

Once you're in, you can read what the agent is doing, split a pane to run tests, or stop the agent and take over. The worker doesn't care. It's a normal terminal.

Give it more room

If a window worker outgrows a single pane, promote it to its own session:

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

Now it has its own tmux lifecycle — multiple windows, multiple panes, whatever it needs.

Clean up

When the work is done and you don't need the worktree anymore:

wtmag cleanup --id project-github-issue-456

WTmag removes the worktree and the tmux target together. If the worktree is dirty and you want it gone anyway:

wtmag cleanup --id project-github-issue-456 --force

Nothing lingers after you're done.