Quick Start

Start by importing your existing agent files into barrel's global directory:

You can also import an entire directory of agents:

Verify your imported agents:

Agents are stored in ~/.config/barrel/agents, making them available across all your workspaces.

In an existing repository, initialize a barrel workspace:

This creates a minimal barrel.yaml in your project:

workspace: my-project

shells:
  - type: claude
    agents:
      - "*"

Launch the Claude shell to see your agents in action:

You'll see output like this:

barrel creates symlinks from your centralized agents to Claude's expected location. This happens for each supported AI (Claude, Codex, OpenCode) - same agents, different destinations.

When the session ends, barrel cleans up the symlinks automatically. Your agents stay in one place, portable across all LLMs.

Update your manifest to include a terminal profile with Claude on the left, and two custom shells stacked on the right:

workspace: my-project

shells:
  - type: claude
    agents:
      - "*"
  - type: shell
  - type: server
    command: npm run dev

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

Start your full workspace:

barrel creates a tmux session named after your project, with all panes arranged according to your profile:

When you're done, kill the workspace to clean up agents and terminate the tmux session:

barrel cleans up symlinks and restores your environment:

For fullstack development, you can create elaborate layouts with multiple AIs and services:

workspace: fullstack

shells:
  - type: claude
    agents: ["*"]
  - type: codex
    agents: ["*"]
  - type: frontend
    command: pnpm dev
  - type: backend
    command: cargo watch -x run
  - type: logs_fe
    command: tail -f logs/frontend.log
  - type: logs_be
    command: tail -f logs/backend.log

terminal:
  profiles:
    default:
      type: tmux
      claude:
        col: 0
        row: 0
      frontend:
        col: 0
        row: 1
      logs_fe:
        col: 1
        row: 1
        color: gray
      codex:
        col: 2
        row: 0
      backend:
        col: 2
        row: 1
      logs_be:
        col: 3
        row: 1
        color: gray

This creates a workspace with two AIs working on different parts of your stack: