Manifest File

The barrel.yaml file defines your workspace configuration: which shells to run, where to find agents, and how to lay out terminal panes.

File Location

barrel walks up the directory tree looking for barrel.yaml. You can also specify a path with the -m flag.

Complete Example

barrel.yaml

workspace: my-project

agents:
  - path: ./agents
  - path: ~/.config/barrel/agents

shells:
  - type: claude
    agents:
      - "*"
  - type: shell
    notes:
      - "$ barrel -k my-project"

terminal:
  profiles:
    default:
      type: tmux
      claude:
        col: 0
        row: 0
      shell:
        col: 1
        row: 0
        color: yellow

Top-Level Fields

workspacestringrequired

Workspace name. Used for the tmux session name and display.

agentsarray

List of directories to search for agent files. First match wins for duplicate names.

agents:
  - path: ./agents
  - path: ~/.config/barrel/agents

shellsarrayrequired

Shell definitions. Each shell can be referenced by type in terminal profiles.

terminalobjectrequired

Terminal configuration with named profiles for different layouts.

Shell Configuration

Each shell in the shells array defines a pane type. Built-in types: claude, codex, opencode. Any other type is treated as a custom shell.

AI Shell (claude, codex, opencode)

- type: claude
  path: ./src
  color: purple
  agents:
    - "*"                    # all agents, or list specific names
  model: sonnet              # sonnet, opus, haiku
  prompt: "Your task..."     # initial prompt
  allowed_tools:             # restrict to specific tools
    - Read
    - Write
  disallowed_tools: []       # block specific tools
  args: []                   # additional CLI arguments
  notes:
    - "reminder note"

typeShell type: claude, codex, opencode, or custom name

pathWorking directory (relative to manifest or absolute)

colorPane color: purple, yellow, red, green, blue, gray, orange

agentsAgent names to load. Use "*" for all agents.

modelModel to use (e.g., sonnet, opus, haiku for Claude)

promptInitial prompt to send when launching

notesNotes displayed in the pane on startup

Custom Shell

- type: server
  path: ./backend
  command: cargo watch -x run
  color: blue
  notes:
    - "Backend server"

commandCommand to execute in this pane

Terminal Profiles

Profiles define how shells are arranged in tmux. Each profile has a type and pane positions.

terminal:
  profiles:
    default:
      type: tmux
      claude:
        col: 0
        row: 0
      shell:
        col: 1
        row: 0
        color: yellow
        height: 50

    focus:
      type: shell
      claude:
        col: 0
        row: 0

Profile Types

tmux - Standard tmux session with panes (default)
tmux_cc - iTerm2 tmux integration mode
shell - No tmux, run first pane directly

Pane Positioning

Each pane name in the profile maps to a shell type. Position with column/row grid:

colColumn position (0, 1, 2...) - left to right

rowRow position (0, 1, 2...) - top to bottom within column

widthColumn width percentage

heightRow height percentage

colorOverride shell color for this profile

shell_typeUse a different shell type than the pane name

Colors

Available pane colors:

purpleyellowredgreenbluegrayorange