For contributors: notes about working with agents and worktrees.

[ValerianRey]

Just a few notes about how I work with claude and worktrees. I might make a better documentation of this one day, but I would like it to be not specific to claude, because I absolutely want to avoid locking in to claude.

Basically, I use wtp to manage worktrees for me.
I thus have a .wtp.yml file at the root of the repo, containing the extra required steps to create the worktrees (basically to copy non-comitted files like CLAUDE.md and .claude, and to install the deps in the newly created worktree):

defaults:
  # Base directory for worktrees (relative to project root)
  base_dir: "../worktrees"

hooks:
  post_create:
    # Copy real files from the MAIN worktree into the NEW worktree
    - type: copy
      from: ".claude/settings.json" # Allowed even if gitignored. 'from' is always relative to the MAIN worktree
      to: ".claude/settings.json" # Destination is relative to the NEW worktree

    - type: copy
      from: "CLAUDE.md"
      to: "CLAUDE.md"

    - type: command
      command: "$HOME/scripts/reinstall-tjd.sh"

For that to work, you need a script reinstall-tjd.sh in the $HOME/scripts folder:
Mine looks like this (this depends on your gpu):

#!/usr/bin/env bash

set -euo pipefail

TARGET_DIR="$(pwd)"
git config --unset-all core.hooksPath 2>/dev/null || true
rm -rf .venv
rm -f uv.lock
uv venv
CC=gcc uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot --index-strategy unsafe-best-match --extra-index-url https://download.pytorch.org/whl/cu126
uv run pre-commit install

Lastly, I have a CLAUDE.md file that links to AGENTS.md, and adds a few extra things:

@AGENTS.md

- When creating a pull request, run `gh label list` to discover available labels, then:
  - Add the `cc: <type>` label that best describes the change. The CI will use it to
    prepend the conventional commit type to the title.
  - If the change targets a specific package, also add the matching `package: <scope>`
    label.
  - If the change introduces a breaking API change, add the `breaking-change` label.
  - Keep the title short enough that once the CI prepends `<type>[(<scope>)][!]: ` and
    GitHub appends ` (#NNN)` on merge, the total stays under 72 characters.
  - The PR message should be short and efficient.

My .claude is more or less empty except for a few permissions that I added there.

I think it's good that worktrees are created outside of .claude/worktrees (where claude puts them by default) and I don't like the claude --worktree command, and I also like to avoid vendor lock-in. So I think it makes perfect sense to use wtp for worktree management. Alternatively we could do that manually, with a script, or with another tool if this one becomes deprecated.

The steps to start working on a new thing are then:

wtp add -b my-feature  # creates a my-feature branch, a my-feature worktree, copies `CLAUDE.md` and `.claude`, and installs deps
code ../worktrees/my-feature  # opens vscode at this worktree's dir
# open vscode terminal
claude  # starts claude at this worktree's dir

There are a few claude-specific things. CLAUDE.md, .claude/ and even the .wtp.yml has to contain claude-specific things. We could maybe have a folder .agents/. Even my command to reinstall torchjd is gpu-specific so I can't really commit it.
So there may be a few things we could commit but not much. But with this setup, it should be rather easy to switch agents. Something like:

• Delete CLAUDE.md and .claude
• Add what's necessary for the new agent
• Update .wtp.yml to make it copy the stuff that's necessary for the new agent, and non-comitted.

Hopefully more and more agent providers will adopt standards to that less stuff has to be changed when changing agents. But I think it's manageable so far.