Skip to main content

​
Two approaches

Trellis supports two ways to run multiple agents:
ApproachDescriptionIsolation
Multi-AgentMultiple agents in the same directoryShared files, can conflict
Multi-SessionEach agent in separate Git worktreeFully isolated, no conflicts
This guide focuses on Multi-Session - the worktree-based approach.

​
Why Multi-Session

Some tasks are independent. Adding a login page doesn’t affect adding a settings page. With separate worktrees, agents can’t interfere with each other. 
main repo
    │
    ├── worktree-1/  →  Session 1 (feature-a)
    ├── worktree-2/  →  Session 2 (feature-b)
    └── worktree-3/  →  Session 3 (feature-c)
Each worktree is a separate checkout on a separate branch. No merge conflicts during development. When done, each session creates a PR. You review and merge.

​
Configuration

Before starting, create worktree.yaml in your project root: 
# worktree.yaml
base_branch: main
worktree_dir: ../.trellis-worktrees # Where to create worktrees
tasks:
  - id: feature-a
    branch: feature/login-page
    prd: |
      Add login page with email/password authentication.
      Include form validation and error handling.
  - id: feature-b
    branch: feature/settings-page
    prd: |
      Add user settings page.
      Allow changing display name and password.
Each task defines:
  • id: Unique identifier
  • branch: Git branch name
  • prd: Requirements for this task

​
Starting parallel sessions

Use the /trellis:parallel command in Claude Code. It reads worktree.yaml and:
  • Creates worktrees for each task
  • Spawns Claude Code sessions
  • Sets up branches
Or use the script directly: 
python3 .trellis/scripts/multi_agent/start.py
Each session runs independently.

​
Monitoring progress

Check status with: 
python3 .trellis/scripts/multi_agent/status.py
Output shows each task’s current phase and branch.

​
Session pipeline

Each session follows phases:
  1. Plan - Understand requirements, identify files to modify
  2. Implement - Write the code
  3. Check - Review against specs, self-fix issues
  4. PR - Create pull request
The check phase has a “Ralph Loop” - if issues are found, it goes back to fix them. This prevents sloppy PRs.

​
When to use this

Good for:
  • Independent features
  • Parallel bug fixes
  • Generating variations (different approaches to same problem)
Not good for:
  • Features that depend on each other
  • Work that touches the same files
  • When you need to iterate with the AI

​
Cleanup

When done, clean up worktrees: 
python3 .trellis/scripts/multi_agent/cleanup.py
This removes worktrees but keeps branches. You can delete merged branches normally.

​
Platform support

FeatureClaude CodeCursor
Multi-Agent (same dir)✅ Full⚠️ Limited
Multi-Session (worktree)✅ Full❌ Not supported
Multi-Session requires Claude Code’s hooks for automatic context injection. You also need enough API credits. Three sessions means three times the token usage.