Overview

WTmag is built around a simple idea: the gap between having a task and having an agent working on it should be one conversation, not a checklist of manual steps. You talk with your orchestrator about what needs doing, and it dispatches workers. Each worker runs in its own worktree and tmux session. You stay in the terminal the whole time.

The two tiers

There are two roles in a WTmag session, and it helps to keep them straight:

The orchestrator is an agent running in your main tmux session. You talk to it. It understands a bundled skill that lets it dispatch workers: brainstorm an issue, flesh it out, point it at an existing ticket, or ask it to pull open work for review. The orchestrator runs wtmag create for each task and tells you how to attach to the workers. It should not attach itself. That's your job.

A worker is an agent running inside a worktree and a tmux session. It does the actual coding. Issue workers try to get to a PR. Review workers read and report. Custom prompt workers do whatever you told them.

you ↔ orchestrator (main tmux session)
              │
              ├── wtmag create --github 456 -t issue
              │     → worktree + tmux window + agent
              │
              └── wtmag create --github 234 -t pr
                    → worktree + tmux window + agent

How a session starts

You open a tmux session on your default branch, load the WTmag orchestrator skill, and start talking. The conversation can go anywhere:

• Work through a rough problem and define it into a task
• Reference an existing ticket by number
• Ask it to pull open issues from whatever sources it's connected to
• Write the task up from scratch

The orchestrator fetches the full context and dispatches workers accordingly: one worker per task, each in its own worktree.

What workers do by default

Issue workers are end-to-end delivery oriented. They implement the task, commit, push the branch, open a PR with gh, and report the link back.

PR review workers are read-only. They inspect the diff, report findings, and don't touch anything: no edits, no commits, no approvals, no merges.

Custom prompt workers do whatever you wrote in the prompt.

Defaults that matter

First run creates ~/.config/wtmag/config.toml. The generated defaults:

• Default agent: pi
• Workers open as tmux windows in your current session (not separate sessions)
• Both implementation and review work default to window placement

So you need to be inside tmux when you run wtmag create with the default config. Windows are lightweight: one extra tab in tmux. When a task grows, promote it into a dedicated session.

The setup you need

WTmag expects a WorkTrunk-managed repo. Bare clone, then check out the default branch:

git clone --bare <repo-url> project/.git
cd project
wt switch ^

^ is WorkTrunk shorthand for the default branch.

Then start tmux from that worktree:

tmux new -s project-dev

Run your orchestrator inside that session. It calls wtmag create for each task. Workers open as windows in the same session by default. You switch to them with tmux-sessionx, wtmag attach, or whatever tmux workflow you already use.