Parallel feature work without merge conflicts

Updated August 10, 2026

Goal: two agents, one repo, no fighting over the working directory.

What you need

  • A gem that is its own git repository. Isolated shards need one, and crystl refuses when the gem’s git root is a parent directory instead of the gem itself.
  • Creating isolated shards from the desktop is not gated. Creating them from the CLI with crystl shard create is a Guild control command.

Steps

  1. Create the first isolated shard. Hover the + in the shard bar and click the worktree row (the branch icon). It’s also on the File menu. crystl forks a worktree from the gem’s integration target, names the branch, installs dependencies, symlinks your gitignored .env files, and drops you into a ready agent session.

  2. Create the second one the same way, and give each agent a different task:

    • shard A: “add user authentication to the API”
    • shard B: “write integration tests for the payment flow”

  3. Or do it from the CLI, which is what an orchestrator agent uses:

    crystl shard create --gem myapp --isolated --prompt "fix #42"
crystl shard create --gem myapp --isolated --crystal-name jade

  4. Fork from something other than main when you need to. Control-click the worktree row and choose new isolated shard from branch… to base a shard on a release line or a teammate’s branch. To change it for every shard in a gem, set the integration target in the gem’s worktrees tab, or with crystl worktree target.

  5. Integrate when a shard is done. See review and merge a worker’s branch safely.

What you’ll see when it works

Each isolated shard carries a branch icon in the shard bar, and a shard with unmerged commits shows a ↑N badge below its tab. The agent is told it’s in a worktree through its system prompt, so it stays scoped and leaves integration to crystl.

Agents in different worktrees can edit the same files without clobbering each other’s checkout. Git may still report a conflict when the branches meet, which is the point: you find out at integration time instead of losing an edit.

Know what the isolation is and isn’t. The write guard blocks structured writes (Claude Code’s Write, Edit, MultiEdit, NotebookEdit, and Codex’s apply_patch) that target the repo outside the shard’s own worktree, even in automatic approval modes. It is not an OS sandbox: arbitrary Bash writes are not generally path-confined, and only the Claude Code and Codex integrations currently pass the denial back to the agent.

Go deeper

  • isolated sessions for the write guard, stale branch recovery, and the worktrees panel.
  • Your work is safe for exactly when crystl will and won’t delete a branch.
  • crystl quest sealed mode when the parallel agents should also talk to each other.