Reference
The command, the shortcuts, and the parts that are worth knowing exactly.
The wortel command
Bundled inside the app and on every session’s PATH, with no installer and no admin prompt. It speaks to the running app over a socket.
| Command | What it does |
|---|---|
| wortel open <path> | Opens a preview window for a file |
| wortel new --branch <name> | A session, in its own worktree |
| wortel new --branch <name> --from <ref> | Forks the new branch from something else |
| wortel rename <name> | Renames the session it was run in |
| wortel notify <text> | This session wants you |
This is how Wortel avoids shipping an integration per agent. An agent that just wrote a file opens a preview of it. A hook you wrote names the session after the ticket you are on. A build that finishes raises attention.
Keyboard shortcuts
| Action | Shortcut |
|---|---|
| New session | ⌘N or ⌘T |
| New section | ⌘⇧N |
| Rename session | ⌘R |
| Close session | ⌘W |
| Previous / next session | ⌘⇧[ ⌘⇧] or ⌘⌥↑ ⌘⌥↓ |
| Jump to session by position | ⌘1 … ⌘9 |
| Jump to the next waiting session | ⌘⌥] |
| Show source control | ⌘⌥G |
| Show files | ⌘⌥E |
| Toggle sidebar | ⌘⌥S |
| Focus the source-control list | ⌘⌥L |
| Find, in a preview window | ⌘F |
| Increase / decrease / reset font size | ⌘+ / ⌘− / ⌘0 |
| Select all (⌘A clears the input line) | ⌘⇧A |
How the agent detection works
Where an agent announces itself, with OSC 9;4 progress, OSC 133 command marks or a spinner in the title, Wortel uses that. None of it is required: the fallback is the screen itself, so an agent that emits nothing is still read correctly, including one that does not exist yet.
Nothing is written into any agent’s configuration to make this work, and detection only runs on sessions you are not currently looking at. A notification never arrives for the session in front of you.
What a worktree session does
The session takes the branch’s name, and a branch that already has a worktree opens the one it has instead of failing.
Its row carries a small branch mark, because the name alone cannot tell you: a session named for its branch otherwise reads as an ordinary shell that happens to be called the same thing, and which one you are looking at decided where your last commit went.
A new branch forks from the repository’s default branch, not from wherever you happen to be standing. Opening one from inside another agent’s worktree would otherwise fork that agent’s half-finished branch, which is a thing you find out about later. Both the dialog and the command let you pick something else to fork from.
The parts underneath
The process holding your shells knows nothing about terminals, git or rendering. It forks what it is told to fork and keeps reading when nobody is attached, which is what makes it small enough to trust with outliving everything else.
Switching sessions costs a single frame because every surface stays alive inside the window. Only the one you had selected starts before the first frame; the rest warm up behind it.
The inspector belongs to the session, because a shell in your home directory never wants it and one inside a repository always does. Cost tracks the window on screen, never the size of the repository: a collapsed node_modules is one row and no work at all.