Rexa Docs
Esc

    Workspace

    Projects and worktrees

    Open repositories as projects and give each task its own worktree.

    A project is a folder you open in Rexa, usually a git repository. A worktree is a separate checkout of that repository on its own branch, created with git worktree. Each worktree has its own tabs, terminals and agents, so parallel tasks never share files.

    The Projects sidebar on the left lists projects, their worktrees, and the agents running in each worktree.

    Open a project

    • ⌘ O, or the + folder button in the Projects header, opens a folder picker.
    • rexa open [path] opens a folder from a terminal and launches Rexa if needed. See the CLI.

    What you pick decides what Rexa opens:

    You pick Rexa opens
    A repository root The project with every worktree git knows about, wherever it lives on disk.
    A folder outside any repository A single-row project with no worktrees.
    A folder inside a repository A prompt: open just that folder, or the repository root.
    A folder holding several repositories A checklist of the repositories found up to three levels deep.

    A subfolder project, such as packages/api in a monorepo, limits the file tree, git changes, language servers and sessions to that folder. It cannot create or delete worktrees; its menu has Open Repository Root.

    Opening a path that is already open selects the existing project.

    The sidebar

    • Drag projects, worktrees and agent cards to reorder them. Click a project to collapse it. Order and folding are saved.
    • Rename a project or worktree to change its display name. Clearing the name brings back the folder name.
    • Hover a project for its path, worktree count and session counts.

    The sidebar takes the keyboard when focused:

    Action Shortcut
    Move J K or ↑ ↓
    Open Space
    Rename ↵
    Collapse / expand H / L
    Copy path ⌘ C
    Reveal in Finder ⌘ ⇧ R
    Hide ⌘ ⇧ H
    Move row up / down ⌥ ↑ / ⌥ ↓

    Create a worktree

    Open the form

    Press ⌘ ⇧ N, click + on a project row, or choose New Worktree from the project’s right-click menu.

    Fill in the fields

    Field Meaning
    Base The branch to start from. Defaults to the main checkout’s branch.
    Branch The new branch to create. Required.
    Name The folder name. Follows the branch, with / turned into -, until you edit it.
    Location The parent folder. Defaults to the folder that holds the project.

    Keep Remember for this project checked to reuse the location next time.

    Create

    Rexa runs git worktree add -b <branch> <location>/<name> <base>. The new worktree appears in the sidebar, selected. Git errors show inside the form.

    Worktrees you add, remove or prune with git worktree in a terminal show up in the sidebar without a restart.

    Switch worktrees

    Action Shortcut
    Worktree picker ⌘ ⇧ W
    Next / previous worktree ⌘ ` / ⌘ ~
    Next / previous agent in the worktree ⌃ ` / ⌃ ~
    Go back / forward ⌃ - / ⌃ ⇧ -

    Typing ~ in quick open (⌘ P) also lists worktrees, grouped by project.

    Remote status

    Each worktree row shows ↑N for commits not pushed and ↓M for commits not pulled. When the branch has a pull request, the worktree icon shows its state: open, draft, merged or closed. The main worktree has its own icon.

    • Counts update after a fetch. Turn on background fetch with git.autofetch in Settings → Git.
    • Pull request state needs the GitHub or GitLab CLI. See Pull requests.
    • Hide both with git.remote_status or the palette command rexa: toggle sidebar remote status.

    Reset a merged worktree

    When a worktree’s pull request is merged or closed, its menu offers Reset Remote Status. Rexa fetches and moves the worktree to the base branch on a detached HEAD, ready for the next task. The branch and its commits are kept. rexa: reset all remote status does this for every eligible worktree at once.

    Hide a worktree

    Hide Worktree removes a worktree from the sidebar and leaves it on disk. Bring it back from the eye icon on the project row, or Hidden Worktrees… in the project menu.

    Delete a worktree

    Delete Worktree in a linked worktree’s menu removes its folder from disk. The main worktree cannot be deleted this way.

    The confirmation lists what happens before you agree:

    • The worktree folder is removed. Its branch and commits are kept.
    • Agent sessions running in it are closed.
    • Uncommitted changes and untracked files in it are lost.

    Remove a project

    The project menu has two removals. Both are refused while agents are running in the project.

    • Remove from Rexa forgets the project. The folder stays on disk.
    • Move to Trash moves the project folder to the macOS Trash. Linked worktrees outside the folder are left alone.

    Toolchains and environment

    Terminals, agents and language servers in a worktree get the project’s toolchains: the active Python .venv and the Node version from .nvmrc, .node-version or volta.node come first on PATH. Pin a different one per project in .rexa/config.json or from the language server status in the status bar. See Language servers.