Skip to main content

​
Two approaches

Trellis supports two ways to run multiple agents: 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.
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:
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:
Each session runs independently.

​
Monitoring progress

Check status with:
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:
This removes worktrees but keeps branches. You can delete merged branches normally.

​
Platform support

Multi-Session requires hooks for automatic context injection (currently supported by Claude Code and iFlow).

​
Agent pipeline

Each multi-session task uses a 6-agent pipeline: You also need enough API credits. Three sessions means three times the token usage.