Sesh Agent Workflow

A sane workflow for running multiple agents (and/or multiple parallel tasks) in the same repo.

Now that you've got AI coding agents chugging away at your codebase, you have a problem: agents are stepping on each other's toes (and maybe yours).

The solution is Git Worktrees: multiple working folders that share the same Git history, but each checks out its own branch. Each agent gets its own worktree.

The workflow (simple + safe)

1. Run these commands from your main project root with develop checked out. Keep develop clean and up to date.
2. Run sesh <branch> to create a sibling worktree for a task/agent. This will branch off of develop into a new copy of the code located next to your main project. The sibling folder will be named <project>-<branch>.
3. When you’re done, run sesh-kill from inside the worktree you want to remove (or remove it manually; instructions below).

---

Install

1. Clone this repository or download the sesh.zsh script to a location of your choice:

git clone <repository-url> ~/.sesh-agent-workflow
# or download sesh.zsh to any directory you prefer

2. Add this line to your ~/.zshrc:

source ~/.sesh-agent-workflow/sesh.zsh

3. Reload your shell configuration:

source ~/.zshrc

Or simply open a new terminal window.

---

Commands

sesh <branch-name>

Creates a new sibling worktree and checks out a new branch from develop.

It will:

• Update develop (fetch + switch develop + pull --ff-only)
• Create a new worktree in a sibling folder named <project>-<branch>
• Install dependencies:
  • By default: detects Node lockfiles and runs the appropriate install in repo root, client/, and server/ (if present)
  • Configurable: see Configuring install commands below

Example:

cd /Users/you/Sites/<project>
sesh bug/secure-ai-endpoint

---

Configuring install commands (portable across projects)

Different projects have different install commands (monorepos, pnpm/yarn, backend-only repos, etc).

To customize installs for a repo, create a file at the repo root of your develop worktree:

• .seshrc (or .seshrc.zsh)

If that file defines a sesh_install function, sesh will call it from inside the new worktree root.

Example (.seshrc):

sesh_install() {
  # Runs from inside the NEW worktree root
  (cd client && npm ci)
  (cd server && npm ci)
}

To skip installs entirely:

export SESH_SKIP_INSTALL=1

sesh-kill

Deletes the current worktree folder and deletes its local branch, but only if:

• The working tree is clean (no changes)
• You are not on develop or main
• You are not inside the develop worktree

Example (run from inside the sesh worktree you want to delete):

sesh-kill

---

Basic worktree commands (no script)

List worktrees

git worktree list

More detail:

git worktree list --porcelain

Create a worktree manually

From your main develop worktree:

git fetch origin
git switch develop
git pull --ff-only
git worktree add -b bug/my-fix ../my-project-bug-my-fix develop

Remove a worktree (safe cleanup)

git worktree remove /path/to/worktree
git worktree prune

Delete a branch (separate from worktree removal)

Worktree removal does not delete branches.

git branch -d branch-name   # safe (won't delete if unmerged)
git branch -D branch-name   # force

Remote (optional):

git push origin --delete branch-name

---

Common gotchas

• “branch is already checked out at …”
  • That branch is currently checked out in another worktree. Use that worktree, or switch it off that branch before checking it out elsewhere.
• “cannot switch branch while merging”
  • Your develop worktree is mid-merge (or mid-rebase/cherry-pick). Finish it (git status → resolve → commit/continue) or abort it, then rerun sesh.
• Don’t delete worktree folders in Finder
  • Prefer git worktree remove … so Git cleans up its metadata.