Organise your Claude Code agents with dock.yaml

Before you start

• One or more Claude Code agents (see creating a Claude Code agent).
• A text editor.
• The names of the repos you want agents to start in.

Steps

1. Create dock.yaml next to your agent files
   Put a file named dock.yaml in the same folder as the agent files it describes, for example beside code-reviewer.md in your team's agents folder.
2. Declare groups
   Under groups:, list each group with a name and an icon. Groups decide how the Agents tab clusters your agents.
3. Describe each agent
   Under agents:, add an entry keyed by the agent's name. Set group to one of your groups, repo to where it should start (a repo name found in your code folders, or an absolute path) and icon.
4. Add commands
   Under the agent's commands:, give each command a label (what you click) and text (what's sent). Put {input} where something you type should go, such as a PR link or a ticket number.
5. Check the Agents tab
   Save the file and open Agents. Each agent shows in its group, with its repo and command count. On its page, the commands are under Start; one with {input} unfolds a field, and Enter starts the chat.
6. Override it for yourself (optional)
   If the shared dock.yaml lives in a team repo, put your own at ~/.config/pairbar/dock.yaml. The personal one overrides the shared one, so you can change groups or commands without touching the team's file.

A complete example

Two groups, a reviewer that starts in a backend repo, and an investigator for incidents. The repo names and prompts are examples.

groups:
  - name: Review
    icon: checkmark.seal
  - name: Investigate
    icon: magnifyingglass
agents:
  code-reviewer:
    group: Review
    repo: my-backend        # a repo name found in your code folders, or an absolute path
    icon: checkmark.seal
    commands:
      - label: Review a PR
        text: "Review this PR: {input}"
      - label: Review my branch
        text: "Review the changes on the current branch against main."
  incident-investigator:
    group: Investigate
    repo: /Users/me/code/ops
    icon: magnifyingglass
    commands:
      - label: Investigate an alert
        text: "Investigate this alert and find the likely cause: {input}"

Where the commands show up

Troubleshooting

An agent's repo isn't used

repo must be a repo name found in your code folders or an absolute path. Try the absolute path.

My changes to the shared dock.yaml don't show

Check for a personal ~/.config/pairbar/dock.yaml: it overrides the shared one.