Using Jj Workspaces

Using jj workspaces

Choose one workspace owner; never create a second workspace for the same task.

Start

First confirm the current checkout is a jj repository:

jj root --ignore-working-copy

Inside Herdr

Let prefix+a create the task-named jj workspace and open its OMP tab. From that checkout, record the existing workspace without --workspace:

hey agent-start \
  --repo "$PWD" \
  --task my-task \
  --runtime omp \
  --model openai-codex/gpt-5.6-sol

Herdr bootstraps OMP in every workspace and adds Hunk only when the checkout has a Git root. Do not launch nested Herdr or create another jj workspace from the new OMP session.

Outside Herdr

Use the deterministic launcher to create and record the workspace:

hey agent-start \
  --repo "$PWD" \
  --workspace "../workspaces/my-task" \
  --base 'trunk()' \
  --task my-task \
  --runtime omp \
  --model openai-codex/gpt-5.6-sol

Both forms print one JSON receipt. Save its receiptPath for done. Without --workspace, the launcher records the current workspace.

The launcher:

• detects jj from live repository state;
• creates the workspace parent but never overwrites an existing destination;
• records stable change and operation IDs under ${XDG_STATE_HOME:-~/.local/state}/dotfiles-agent-runs/;
• refuses to initialize jj inside a Git-only checkout or Codex Git worktree.

Git worktree boundary

Agent runtimes such as Codex Desktop can create Git worktrees before the agent starts. Do not run jj git init --colocate inside one: nested metadata would not safely convert the primary repository. Finish that task with Git. Initialize jj once from the primary checkout in a separate task; later agents can use jj workspaces from that repository.

Workspace model

• Each workspace has its own working-copy commit @.
• Workspaces share commit history and the operation log.
• Mutating one workspace's @ does not directly move another workspace's @.
• Repository-wide operation recovery can affect concurrent work. Inspect jj op log and coordinate before jj undo or jj op restore.
• In Herdr, task names are durable; workspace, tab, and pane IDs are live handles. Re-read them after lifecycle changes.
• Review with Hunk from the Git root when available. In pure jj, use jj diff --git -r @ in OMP and record findings plus check output in the worklog when present, otherwise in the final handoff.

Stay on one task per workspace. Read other changes with jj diff -r, jj file show -r, and jj log -r; do not use jj edit merely to inspect.

Verify

jj workspace list
jj status
jj log -r '@-::@ | trunk()'

Run the repository's baseline checks before editing. If they fail, record the failure in the receipt/worklog and do not attribute it to the task.

Finish

Use the global done skill. It shapes the task, rebases only its explicit range, publishes the task workspace's explicit bookmark, proves remote equality, records the receipt, and cleans this workspace last.