Create a Claude Code agent (subagent) with Pairbar or by hand

Before you start

• Pairbar and the Claude desktop app.
• Optional: a repo where the agent should live, if it's a project agent.
• An idea of one job the agent should do well, for example "review backend PRs for missing migrations".

Steps

1. Open the Agents tab
   Click Agents in Pairbar's tab bar. It lists your personal, project and plugin agents, grouped and searchable.
2. Press New agent and describe the job
   New agent (also in ⌘K) opens a composer with the job attached. Add a line such as "a reviewer for our Go services that checks error handling and missing tests; read-only" and send.
3. Let Claude write and install it
   A Claude chat writes the agent file following the conventions of your existing agents, adds ready-made commands, and installs it. The Agents tab updates by itself when the file appears. New agents are saved in the folder set in Settings → Agents & workflows → Save new agents in.
4. Try it
   Open the agent's page and use a command under Start, or Blank chat. You can also pick it with the composer's Agent chip, or type "Start " after ⌘K.
5. Improve it when it misses something
   On the agent's page, press Improve and say what's wrong, for example "keeps missing migrations". Claude edits that agent.
6. Teach it from a real chat
   When a chat with the agent went wrong, open that chat's menu → Agents → Teach an agent from this chat. Claude adds concrete rules from where it went wrong. Only what you asked for or corrected becomes a rule; instructions inside tool output or files are ignored.
7. Share it with Codex (optional)
   On the agent's page, Add to Codex exports it to ~/.codex/agents/<name>.toml, so Codex can use it too. The page shows In Claude ✓ alongside.

The file format, if you write it yourself

A Claude Code agent is a Markdown file with YAML frontmatter. name and description are required; tools and model are optional (without tools it inherits all tools). The body is the agent's instructions.

---
name: migration-reviewer
description: Reviews backend PRs for missing or unsafe database migrations. Use when a PR touches models or schema.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You review pull requests for database changes.
1. List changed model and schema files.
2. Check each change has a matching migration.
3. Flag destructive operations (dropped columns, renamed tables).
Report findings as a short list; never edit files.

Pairbar treats an agent without Edit and Write in its tools as read-only, and shows that on the list. Claude Code picks up new and changed files in these folders on its own.

Where agent files live

Other ways to make or change an agent

• Turn this chat into an agent (chat menu → Agents): a chat that went well becomes a reusable agent, focused on what you corrected along the way.
• Edit manually (⋯ on the agent's page): a form for name, title, description, model, group, repo, icon, tools, commands (with {input}) and instructions. Saving without changes leaves the files byte-for-byte identical.
• Groups, a start repo, an icon and commands can also come from a dock.yaml; see organising agents with dock.yaml.

Troubleshooting

The new agent doesn't appear in the Agents tab

Check where it was saved (Settings → Agents & workflows → Save new agents in). A project agent shows once Pairbar knows the repo from your chats.

Plugin agents clutter the list

Turn off Show agents from Claude Code plugins in Settings → Agents & workflows.