Skip to content
Skills Library
Programming · Automation

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.

Repository
dotfiles ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

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

  1. Start
  2. Git worktree boundary
  3. Workspace model
  4. Verify
  5. Finish
Original SKILL.md headings · 79 lines, 474 words
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

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.