Skip to main content

​
Bring Your Own Agent (BYOA)

Genie is an orchestration layer, not an AI provider. It manages teams, worktrees, messaging, state, and task dispatch — the agent that does the actual coding is pluggable. We have strong opinions about orchestration. We have zero opinions about your model vendor. Today, Genie ships with built-in adapters for Claude Code and Codex. But the architecture is designed so that any CLI-based agent can be plugged in as a provider. The agent is the muscle. Genie is the brain.

​
Why BYOA Matters

  • No vendor lock-in — switch providers without changing your workflow
  • Best tool for the job — use Claude for reasoning-heavy tasks, Codex for fast iteration
  • Cost control — mix expensive and cheap models in the same team
  • Future-proof — new agents appear constantly; Genie adapts without rewriting your setup
  • Team flexibility — different team members can prefer different agents

​
Supported Providers

Built-in providers work today with genie spawn --provider. Planned providers follow the same adapter pattern and can be contributed as community adapters.

​
The --provider Flag

Every genie spawn command accepts a --provider flag that selects which AI provider backs the agent:
The default provider is claude. When you specify a different provider, Genie translates your spawn options into the provider-specific CLI invocation.

​
Examples

​
What Changes Between Providers

Genie normalizes the interface, but each provider has its own capabilities:

​
What Stays the Same

Regardless of provider, Genie handles:
  • Agent registry — all agents tracked in PostgreSQL
  • Messaging — genie send works the same for any provider
  • Team chat — broadcast messages reach all agents regardless of provider
  • Task dispatch — wish execution groups are provider-agnostic
  • Lifecycle — genie ls, genie stop, genie kill work uniformly
  • Worktree isolation — git worktrees are shared infrastructure, not provider-specific

​
Auto-Respawn Templates

When Genie spawns an agent, it saves a template — a snapshot of the spawn configuration. If an agent goes offline (tmux pane dies, process crashes), Genie can automatically respawn it from the saved template.

​
How It Works

  1. Spawn — You run genie spawn engineer --provider codex --team auth-fix
  2. Template saved — Genie stores the spawn config in the agent registry:
  1. Agent goes offline — The tmux pane dies or the process exits
  2. Message triggers respawn — When another agent (like the team-lead) sends a message to the offline agent, Genie’s auto-spawn hook detects the dead pane and respawns from the template
  3. Same config, fresh process — The respawned agent gets the same provider, team, role, and working directory

​
Template Resolution

When a message targets an offline agent, the auto-spawn handler:
  1. Checks the agent registry for a live tmux pane — skips if the agent is alive
  2. Looks up the agent in the directory for identity resolution
  3. Searches saved templates by name, ID, or role within the team
  4. Spawns using the matched template’s provider and configuration
Auto-respawn is triggered by message delivery, not by a heartbeat or timer. If no one sends a message to a dead agent, it stays dead. This is intentional — it prevents unnecessary respawns of agents that are no longer needed.

​
Template Fields

​
Multi-Provider Team Patterns

​
Pattern 1: Specialization

Problem: Different tasks need different strengths. Reasoning-heavy architecture work benefits from a stronger model, while straightforward implementation can use a faster, cheaper agent. Solution: Assign providers based on task type within the same team.
Benefit: Each agent uses the tool best suited to its role. The team-lead reasons about architecture with Opus, engineers iterate quickly with Codex, and the reviewer catches issues with Sonnet. Trade-off: Mixed providers mean mixed capabilities — Codex agents won’t have Claude’s native team integration features like session resume. When to use: Teams with diverse task types — architecture + implementation + review in the same wish.

​
Pattern 2: Cost Optimization

Problem: Running every agent on Claude Opus is expensive. For a 5-agent team running 2 hours, model costs add up fast. Solution: Use the most capable (and expensive) model only where it matters. Use cheaper providers for high-volume, lower-complexity work.
Benefit: 60-70% cost reduction compared to running all agents on Opus, with minimal quality loss on implementation and testing tasks. Trade-off: Cheaper models may miss subtle issues that Opus would catch. Mitigated by using Opus for the reviewer role. When to use: Large teams, long-running wishes, or budget-conscious workflows where not every agent needs the strongest model.

​
Pattern 3: Manual Failover

Problem: A provider goes down or hits rate limits during an active wish. Your team is blocked. Solution: Manually respawn affected agents with a different provider. Genie’s orchestration layer is provider-agnostic — switching providers doesn’t lose team state, messages, or wish progress.
Benefit: No single provider failure blocks your entire team. Wish state, messages, and task progress are preserved across provider switches. Trade-off: Manual intervention required — Genie does not automatically detect provider outages or switch providers. You need to notice the failure and respawn. When to use: Production incidents, rate limit situations, or when a provider’s API is degraded. Also useful for testing how your wish performs across different agents.
Failover is manual by design. Automatic provider switching introduces complexity around session state, model capability differences, and cost surprises. Manual failover keeps you in control.

​
How Provider Adapters Work

Under the hood, each provider is a function that translates SpawnParams into a shell command:
The adapter handles:
  • Binary selection — which CLI to invoke (claude, codex)
  • Flag translation — mapping Genie options to provider-specific flags
  • Environment setup — setting GENIE_AGENT_NAME, GENIE_TEAM, etc.
  • Preflight checks — verifying the provider binary exists on PATH
Genie owns everything else: agent registry, messaging, team state, task dispatch, worktree management, and lifecycle commands. The provider is just the process that runs inside the tmux pane.

​
Adding a New Provider

Provider adapters live in src/lib/provider-adapters.ts. Each adapter implements a build*Command() function that takes SpawnParams and returns a LaunchCommand:
To add a new provider:
  1. Add the provider name to the ProviderName type
  2. Implement a build*Command() function
  3. Add a case to the buildLaunchCommand() switch
  4. Ensure the binary passes the preflightCheck()
The adapter pattern means new providers don’t touch orchestration logic — they only need to know how to launch their CLI binary with the right flags.

​
Best Practices

Claude Code is the default for a reason — it has the deepest integration with Genie (native teams, session resume, model selection). Use it unless you have a specific reason to switch.
Use stronger providers for tasks that require reasoning (architecture, review, debugging). Use faster/cheaper providers for straightforward implementation and testing.
The team-lead orchestrates the entire wish lifecycle. It benefits most from Claude’s native team integration and session resume capabilities.
Don’t start with a multi-provider team. Get the wish working with a single provider, then optimize by switching specific roles to cheaper alternatives.
When using mixed providers in a team, note why in the wish or team config. Future you (or your teammates) will want to know why the QA agent is on Codex.

​
Questions?

Something not working with your provider setup? Adapter behaving weird? Want to argue about whether Codex or Claude is better for review tasks? (Spoiler: we have opinions, but we’ll let you form your own.)

Ask on Discord

Provider questions, adapter help, and healthy debates about which AI is best at what.