Sessions

axel 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 axel 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 axel, it creates a tmux session named after your workspace:

Launch

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

$ axel

Detach

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

Reattach

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

$ axel

Kill

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

$ axel -k my-project

Managing Sessions

Use axel session commands to manage your workspaces:

axel session list

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

$ axel session list

axel session join <name>

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

$ axel session join my-project

axel session kill [name]

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

$ axel session kill my-project

Git Worktrees

Git worktrees let you check out multiple branches simultaneously in separate directories. axel 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:

$ axel -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 axel.yaml to the worktree
Launches the workspace from the worktree directory

Directory structure after running the command:

~/code/

├── myproject/ # main repo

│ ├── axel.yaml

│ └── src/

└── myproject-feat-auth/ # worktree

├── axel.yaml → ../myproject/axel.yaml

└── src/

To clean up a worktree when you're done:

$ axel -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

❯ axel -w feat/auth

# Terminal 2: Bug fix on main

❯ axel

# Terminal 3: Another feature

❯ axel -w feat/payments

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