Adding an agent
Everything that knows how one agent works lives in src/providers/<id>/. Claude Code is src/providers/claude/, and Codex is src/providers/codex/, a smaller one worth reading first. The rest of perch only talks to the Provider interface in src/providers/types.ts.
What a provider does
Section titled “What a provider does”A new agent needs only two things:
- find its accounts
- find its running sessions
It can also:
- read conversations (and helper agents)
- list slash commands
- start itself in a terminal, resuming or forking a conversation
- read and answer its menus on a tmux screen
- answer permission prompts
- take a reply for a session it can’t be typed into (Codex:
codex queue) - list the helper agents it has working, and the ones you’ve set up
- say where its conversation file is, so tasks know which session wrote them
- report usage and context size
Whatever it leaves out simply doesn’t show for its sessions.
Hooking it up
Section titled “Hooking it up”List the new provider in src/providers/index.ts. Pull requests welcome.