using-jj-workspaces
/using-jj-workspaces
Creates or records isolated jj agent workspaces. Use when starting jj task work, entering a Herdr-created workspace, or handling an agent-created Git worktree boundary.
- Author
- edmundmiller ↗
- Repository
- dotfiles ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Creates or records isolated jj agent workspaces. Use when starting jj task work, entering a Herdr-created workspace, or handling an agent-created Git worktree boundary.
Original author description
Creates or records isolated jj agent workspaces. Use when starting jj task work, entering a Herdr-created workspace, or handling an agent-created Git worktree boundary.
How it works
- Start
- Git worktree boundary
- Workspace model
- Verify
- Finish
SKILL.md preview
---
name: using-jj-workspaces
description: Creates or records isolated jj agent workspaces. Use when starting jj task work, entering a Herdr-created workspace, or handling an agent-created Git worktree boundary.
---
# 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:
```bash
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`:
```bash
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:
```bash
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
```bash
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.
Versions
The database has no other skills named using-jj-workspaces.
Database snapshot: 13.11.2026 · package version 85aaa3fca969 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100worktree
Git worktree lifecycle management. Use when team needs parallel isolated workspaces for multi-stream development, or when an experiment must not touch the main working tree. Creates isolated workspaces, manages branches, handles cleanup. Called by team and cook. - 96using-git-worktrees
Use this whenever you need to create an isolated workspace. - 100use-git-worktree
This skill should be used when starting feature work that needs isolation from current workspace - creates isolated git worktrees with smart directory selection and safety verification - 95herdr
Control Herdr, a terminal multiplexer for coding agents. Use only when the user explicitly mentions Herdr or asks to use Herdr to inspect or control panes, tabs, workspaces, commands, or another agent. Do not use merely because a task could benefit from a background terminal,… - 100git-worktree
Manage Git worktrees for parallel development. Use when creating isolated workspaces for parallel feature work, running multiple Claude sessions simultaneously, or managing concurrent development tasks. - 98using-git-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates an isolated git worktree (via the native opencode v2 worktree tools) and moves the session into it