Bringing work home

The local machine stays the source of truth for your repository. Work goes to the server as a commit when a workspace is created, and comes back to the local machine with merge or remote pull.

Merging

workrex merge my-feature

This copies the workspace’s branch, staged and unstaged changes and untracked files into a local worktree, runs your normal local merge there, then removes the remote workspace, its agent and its branch. merge_strategy, --rebase, --squash, --into and --keep work as for a local worktree, and pre_merge hooks run on the local machine.

Preparing the merge worktree

The local worktree gets your files and post_create hooks, but has no panes, so pane commands never run there. Files ignored by Git, such as node_modules, don’t come from the server either. If pre_merge needs dependencies, install them in post_create or share them with files:

post_create:
  - cd docs && bun install
pre_merge:
  - just check

Keep setup hooks repeatable: they run for every fresh merge attempt. If setup fails, the merge stops and the remote workspace stays.

Flag	Skips
--no-verify	pre_merge hooks
--no-hooks	all hooks, including post_create; files still apply

Uncommitted work, conflicts and cleanup

• Unstaged changes and untracked files on the server refuse the merge unless you pass --ignore-uncommitted or --keep. With --ignore-uncommitted, they aren’t merged and are removed with the workspace.
• On a conflict, resolve it in the local worktree and run workrex merge my-feature again.
• If the agent changed the workspace after its work was copied, the remote workspace is kept and the merge says so.
• If the server can’t be reached after the merge, its cleanup is left pending. The next command that reaches the server finishes it without merging again.
• With --keep (or merge_keep: true), the remote workspace and agent stay, and the remote branch moves to the merged result.

Operation logs

A merge or removal requested from a remote pane runs in the background on the local machine. Its output, including hook output, is saved on the local machine:

workrex remote logs devbox                # list log files
workrex remote logs devbox r0123456789ab   # print one request's output

The pane prints the exact command for its request. Logs are private files under ~/.local/state/workrex/remote/<remote>/operation-logs/, readable without a connection to the server. They may contain sensitive hook output and aren’t deleted automatically. Hook output never goes to the server.

This state path keeps its workrex name. See configuration.

Rebasing

workrex rebase my-feature

Sends the local machine’s base branch to the server and rebases the workspace there, committing as your local Git identity. The agent keeps running. Conflicts stay on the server: run workrex open my-feature and resolve them in the remote worktree.

Moving a workspace to the local machine

workrex remote pull my-feature

Stops the remote agent, brings the branch, staged and unstaged changes and untracked files home as a local worktree, opens its window and removes the remote workspace. The window runs your configured panes, so a fresh local agent starts there; the remote agent’s conversation isn’t carried over. Pass --no-hooks to skip the local post_create hooks.

What doesn’t come home

Merge and remote pull carry commits, staged and unstaged changes, and untracked files. They don’t carry:

• files ignored by Git, such as build output or .env files edited on the server
• the contents of submodules, only the recorded commit
• agent state, such as conversations and caches

An untracked nested Git repository, an unfinished merge, rebase or cherry-pick, or a detached HEAD in the remote worktree blocks the copy until you resolve it on the server.

Pushing

Agents on the server can’t push to your Git hosting: the server has no origin and no credentials for it. Bring the work home with merge or remote pull, and push from the local machine.