Agents

Write your prompts once, deploy them to any LLM. Agents are markdown files that barrel automatically symlinks to each tool's expected location.

How Agents Work

Each LLM tool expects agent files in different locations. Claude Code looks for CLAUDE.md or .claude/, Codex uses AGENTS.md, and others have their own conventions.

barrel solves this by letting you store agents in a single location and automatically creating the appropriate symlinks when you launch an assistant via barrel.

Agent Locations

Agents can be stored in two locations:

Local - ./agents/ in your workspace
Global - ~/.config/barrel/agents/ shared across workspaces

Local agents take precedence. You can fork global agents to customize them per-project, or link them to keep them in sync.

Agent File Structure

Agents are markdown files with optional YAML frontmatter:

agents/rust-developer.md

# Rust Developer

You are an expert Rust developer.

## Guidelines

- Write idiomatic Rust code
- Use proper error handling with Result and Option
- Prefer zero-cost abstractions
- Follow the Rust API guidelines

The filename becomes the agent name. Use barrel agent list to see all available agents.

Agent Commands

barrel agent list

List all available agents, both local and global. Shows agent name, location, and description.

$ barrel agent list

barrel agent import <path>

Import an agent file or directory to the global agents directory. This is the recommended way to add existing agents to barrel.

$ barrel agent import ./.claude/agents/web-developer.md

barrel agent new [name]

Create a new agent. If no name is provided, you will be prompted.

$ barrel agent new code-reviewer

barrel agent fork <name>

Copy a global agent to your local workspace. Use this when you need to customize a shared agent for this project.

$ barrel agent fork rust-developer

barrel agent link <name>

Create a symlink from a global agent to your local workspace. Changes to the global agent will be reflected in this workspace.

$ barrel agent link web-developer

barrel agent rm <name>

Remove an agent. If the agent exists in both locations, you'll be prompted to choose which one to remove.

$ barrel agent rm old-agent

Using Agents in Workspaces

Reference agents in your barrel.yaml:

barrel.yaml

shells:
  - type: claude
    agents:
      - rust-developer
      - code-reviewer
    model: opus

  - type: codex
    agents:
      - rust-developer

Use "*" to load all available agents:

barrel.yaml

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

When you launch an assistant via barrel, it installs the agents to each tool's expected location and cleans them up when the session ends.

How Symlinks Work

When you run barrel claude, barrel:

Creates symlinks from your agents to ~/.claude/agents/
Launches Claude Code with your agents pre-loaded
Cleans up the symlinks when the session ends

The same process applies for Codex, OpenCode, and other supported assistants—each gets symlinks in their expected location.