Sessions

barrel uses tmux to create persistent, reproducible workspaces. Combined with git worktrees, you can run multiple branches simultaneously—each with its own isolated environment.

Why tmux?

Sessions persist. Close your terminal by mistake, your IDE crashed and ran out of memory—your workspace survives. Just run barrel again to reattach. Your Claude conversation, running servers, and shell history are all preserved.

Layouts are reproducible. Define your pane arrangement once in YAML. Every time you launch, you get the exact same setup—Claude on the left, servers on the right, logs at the bottom. No manual window management.

Session Lifecycle

When you run barrel, it creates a tmux session named after your workspace:

Launch

barrel creates the tmux session, installs agent symlinks, and spawns all configured panes.

$ barrel

Detach

Press Ctrl+b d to detach. The session keeps running in the background.

Reattach

Run barrel again to reattach to an existing session. No restart, no lost state.

$ barrel

Kill

When you're done, kill the session to clean up agents and terminate processes.

$ barrel -k my-project

Managing Sessions

Use barrel session commands to manage your workspaces:

barrel session list

List all running barrel sessions with their status and working directory.

$ barrel session list

barrel session join <name>

Attach to an existing session. If already in tmux, switches to that session.

$ barrel session join my-project

barrel session kill [name]

Kill a session by name, or the current session if no name is provided.

$ barrel session kill my-project

Git Worktrees

Git worktrees let you check out multiple branches simultaneously in separate directories. barrel integrates with worktrees so each branch gets its own isolated workspace.

The problem with branches

Traditional git workflows force you to stash, switch, and context-switch constantly. Working on a feature when a hotfix comes in? Stash everything, switch branches, fix, switch back, pop stash. Painful.

The worktree solution

With worktrees, each branch lives in its own directory. No stashing, no switching. Run Claude on your feature branch in one terminal while fixing a bug on main in another.

Launch a workspace in a worktree with the -w flag:

$ barrel -w feat/auth

This command:

Creates a worktree for feat/auth if it doesn't exist
Creates the branch from your default branch if needed
Symlinks your barrel.yaml to the worktree
Launches the workspace from the worktree directory

Directory structure after running the command:

~/code/

├── myproject/ # main repo

│ ├── barrel.yaml

│ └── src/

└── myproject-feat-auth/ # worktree

├── barrel.yaml → ../myproject/barrel.yaml

└── src/

To clean up a worktree when you're done:

$ barrel -w feat/auth -k myproject-feat-auth --prune

Parallel Development

Combine sessions and worktrees for true parallel development. Run multiple workspaces simultaneously, each with its own branch and Claude instance.

# Terminal 1: Feature work

❯ barrel -w feat/auth

# Terminal 2: Bug fix on main

❯ barrel

# Terminal 3: Another feature

❯ barrel -w feat/payments

List all your running sessions to see what's active: