Agent · Available now

Ensemble Agent

Gets several genuinely different approaches on the table and argued out before a single line is written.

Ensemble Agent turns one task into a decision before it turns it into a diff. It reads your task and invents a set of specialist perspectives to look at it from, writing each one's full brief itself rather than picking from a fixed list, so the perspectives fit this task instead of being generic roles. Each specialist then works on your task at the same time, in its own copy of your repository that it is not allowed to write to. Each one comes back with five to ten distinct approaches, every one with its upsides, its downsides, its risks, and the files it would touch. You choose how many specialists with one flag, anywhere from 3 to 100.

Then it narrows. A selector reads every approach from every specialist and cuts the field in rounds, keeping about a fifth each round, weighing the trade-offs of what it keeps and recording why everything else was dropped. What survives is one approach and a written brief explaining the choice. Only at that point does a single write-enabled agent get your repository and implement it. That final agent is the only one in the whole run permitted to change a file, and the read-only restriction on the others is enforced by the sandbox rather than by asking them nicely.

It decides how to do the work; it does not attack work that is already finished or push an approach you already chose. If one specialist fails or runs past its five-minute bound, that is reported and the run continues, because a partial slate still beats a single opinion. The run stops only when every specialist has failed. The selector's written reasoning, including the rejected approaches, is part of what you keep.

runtime
local
one-time
ensemble
multi-agent
approach-exploration
architecture-decisions
trade-off-analysis
read-only-proposals
parallel-proposals
selection-rounds
decision-records
design-review
blast-radius
anchoring-bias
role-generation
refactor-planning

Use cases

01
You ask an agent how to solve something and it commits instantly to the first approach it thought of. For the rest of the session it defends that approach, and every alternative you raise comes back as a small variation on the same idea. You cannot tell whether the approach is good or just first. The decision gets made by whichever idea happened to come out of the model before any other.
How the agent solves it
Run the ensemble from the repository root with the task stated as a problem, not as a solution. The default of three specialist roles is enough to break the single-approach anchor, because each role proposes independently without seeing the others. You get the alternatives with their trade-offs written down instead of having to think of them yourself. Read the selector's brief to see why the winner won and why the others lost. Then let the final agent implement the chosen approach, or stop and implement a different one yourself.
What to run
1. Command
```
vidbyte-cli runtime same-host-ensemble "Search results are slow for large accounts. Find the best way to make them fast without changing the API." --roles 3
```
What you get
A real choice between independent approaches instead of a defended first guess.
- Fifteen to thirty approaches from three perspectives that never saw each other's work.
- A selector brief that explains the winner and names why the rest were dropped.
- The chosen approach implemented, with nothing else in the working tree changed.
02
You are about to make an architectural decision that will be expensive to reverse, and the only opinion in the room is yours. There is no time for a design review, and asking a single agent just gives you a confident second opinion from something that already agrees with how you framed it. Once the code exists, the decision will have momentum. If it is wrong, you will find out months from now.
How the agent solves it
Raise the role count so the slate covers genuinely different framings, and put the constraints in the task text: what must not change, what has to keep working, and what you are optimizing for. More roles give the selector a wider field to narrow, which matters most when the decision is hard to undo. Read the selector's reasoning as the main artifact, not just its pick. If you disagree with the winner, the runner-up approaches and their trade-offs are already written down. You make the call with the alternatives in front of you.
What to run
1. Prompt
  Paste this page's copy prompt into your coding agent and answer its questions, so the task text states the constraints and what the decision should let you do.
2. Command
```
vidbyte-cli runtime same-host-ensemble "<task text from the prompt>" --roles 8 --reasoning-effort high
```
What you get
An irreversible decision made against a wide field of written alternatives.
- Eight independent framings of the decision, each with its own approaches.
- Round-by-round reasoning for what was kept and what was cut.
- A record you can show anyone who later asks why this design was chosen.
03
You want options considered, but you do not want an agent editing your repository while it is still deciding what to do. General agents explore by changing files, so by the time you see their thinking your working tree is already full of half-finished experiments. Cleaning that up costs more than the exploration was worth. You end up asking for plans in chat, which lose the file-level detail that makes a plan useful.
How the agent solves it
Run the ensemble and let the read-only restriction do the work. Every specialist explores in its own fork that the sandbox forbids from writing, so the proposals can reference real files without touching them. Only one agent ever gets write access, and only after an approach has been chosen. Your working tree stays exactly as it was until that final stage. If you only want the proposals, stop before the implementation and discard nothing, because nothing was changed.
What to run
1. Command
```
vidbyte-cli runtime same-host-ensemble "Propose how to split the monolithic settings page into sections without changing its URLs." --roles 4
```
What you get
Exploration with file-level detail and a clean working tree.
- Proposals that name the exact files each approach would touch.
- No experimental edits left behind by the exploration.
- Exactly one set of changes, made after the decision rather than during it.
04
Your team keeps relitigating the same technical decision, because nobody wrote down why the rejected options were rejected. Every few months someone new proposes one of them again, and the discussion starts from zero. The reasoning lived in one meeting and one person's memory. Without a record, the decision is only as stable as whoever remembers it.
How the agent solves it
Run the ensemble on the decision itself and keep the selector's output. The selector records why each dropped approach was dropped, round by round, which is exactly the part of a design discussion that normally disappears. Commit the brief next to the code or link it from the decision's ticket. When the rejected option comes up again, the answer is already written. You can also rerun the ensemble if the constraints have genuinely changed.
What to run
1. Command
```
vidbyte-cli runtime same-host-ensemble "Decide between polling and webhooks for syncing invoices, given our retry and ordering requirements." --roles 5
```
2. Prompt
  Ask your coding agent: "Turn the selector's brief into docs/decisions/invoice-sync.md, keeping every rejected option and its reason."
What you get
A decision with its rejected alternatives written down where the team can find them.
- Each rejected approach listed with the reason it lost.
- A decision record committed next to the code it governs.
- A shorter conversation the next time someone proposes a rejected option.
05
A refactor could be done four different ways, and you cannot tell which one is cheapest until you know which files each one touches. Estimating blast radius in your head is guesswork, and the guess usually favors the approach you already like. Picking wrong means a refactor that spreads into modules you did not plan to change. By the time you notice, the work is half done.
How the agent solves it
Describe the refactor and let the specialists propose. Each approach comes back with the files it would touch, so you can compare blast radius directly instead of estimating it. The selector weighs that alongside risk and benefit when it narrows the field. Read the brief, check the file lists against what you expected, and let the final agent implement the winner. The refactor you run is the one whose reach you saw beforehand.
What to run
1. Command
```
vidbyte-cli runtime same-host-ensemble "Move request validation out of route handlers into one shared layer, touching as few modules as possible." --roles 4
```
What you get
A refactor chosen by comparing real file lists, not guessed reach.
- The affected files listed for every candidate approach.
- A winner chosen partly on how far its changes spread.
- An implementation that stays inside the files the brief named.
06
You want a second opinion, but every agent you ask gives you the same opinion. They are all the same kind of model with the same default framing, so asking three times is asking once. Rephrasing the question produces rephrased answers. You need perspectives that differ because the problem has different angles, not because the wording changed.
How the agent solves it
Use a higher role count and be specific about the task, because the planner writes each role's complete brief from what you describe. The differentiation comes from perspectives invented for this problem, such as a data-integrity view, a latency view, and a migration-cost view, rather than from generic hats. Each role proposes in isolation, so no perspective gets pulled toward another. Compare the approaches across roles to see where they genuinely disagree. Those disagreements are usually where the real decision is.
What to run
1. Command
```
vidbyte-cli runtime same-host-ensemble "Our job queue loses work when a worker restarts mid-task. Propose fixes, considering data integrity, latency, and operational cost." --roles 6
```
What you get
Perspectives that actually differ, and a clear view of where they disagree.
- Six role briefs written specifically for this problem.
- Approaches from each role that the others never influenced.
- The points of genuine disagreement surfaced instead of averaged away.
07
The problem is subtle enough that a fast answer is the wrong answer. Concurrency bugs, security boundaries, and data migrations all look simple at a glance and fail in the details. A quick proposal gets the shape right and the edge case wrong. You want every perspective to think hard, and you want them all to think equally hard so their approaches are comparable.
How the agent solves it
Raise the reasoning effort for the whole run, and pin the model if you care which one is making the call. Both settings are forwarded to every turn and every fork, so each specialist works under the same conditions. That keeps the comparison between approaches like-for-like, instead of one branch looking better because it happened to think longer. State the subtle part of the problem explicitly in the task text. The selector then weighs approaches that were all produced with the same care.
What to run
1. Command
```
vidbyte-cli runtime same-host-ensemble "Two workers can claim the same job under load. Propose fixes and state the exact race each one closes." --roles 4 --reasoning-effort xhigh --model <model>
```
What you get
Careful approaches to a subtle problem, produced under identical conditions.
- Every specialist working at the same reasoning effort on the same model.
- Approaches that each name the specific failure they prevent.
- A comparison you can trust, because no branch had an unfair advantage.

Why use this agent

A general agent gives you one approach, and it gives it to you immediately. That speed is useful for small, reversible work and harmful for anything else, because the first approach is not chosen; it is the one that came out of the model first, and everything after that is rationalization. You can ask for alternatives, but you are asking the same agent that already anchored on one answer, in the same context. That produces variations on a theme rather than genuinely different framings. This agent gets the alternatives generated in parallel by separate agents that have not seen each other's work, which is the only cheap way to get real variety instead of rephrasing.

The second problem it addresses is that a general agent decides and implements in the same breath, so by the time you see the decision it is already a diff. Reviewing a diff is a bad way to evaluate an approach, because the alternatives are invisible and the thing in front of you has momentum. Here the two phases are separated by design. Proposals are made under a sandbox that physically prevents writes, the narrowing is a written argument with the rejected candidates recorded, and only the winning approach ever touches your working tree. You get to disagree before the code exists rather than after.

The third is that this kind of exploration is normally too much work to be worth it. Getting five colleagues to each write down several approaches with pros, cons, risks, and affected files is a week of meetings, and doing it yourself is an afternoon you will not spend. Here it is one command. That changes which decisions are worth exploring properly: not just the ones important enough to schedule a design review for, but any decision where you suspect the obvious answer is not the best one. The threshold for taking a decision seriously drops, and that is the real product.

Anchoring on the first idea
Proposals are generated independently and in parallel. The slate is not variations on whatever came out first. You are choosing between options rather than reacting to one.
Alternatives that barely differ
The planner writes each specialist's brief from your specific task rather than assigning generic roles. The perspectives differ because the task has genuinely different angles. Nobody is just putting on a different hat.
Decisions arriving as diffs
The proposal phase cannot write to your repository at all. The point at which you can still disagree cheaply comes before any code exists. Disagreement stops being a revert.
Read-only by request only
The restriction is enforced by the sandbox, not requested in a prompt. An agent that decides it should just make the change quickly is not able to. The only writer is the one that runs after the decision.
Unknown blast radius
Every proposal comes back with its pros, cons, risks, and the files it would touch. Blast radius becomes a fact you compare rather than a guess you make afterwards. That is often what separates two approaches that both work.
Rejected options vanishing
The selector records why each dropped candidate was dropped, round by round. That is the part of a design discussion that normally survives only in one person's memory. It is why the same decision gets relitigated three months later.
Exploration too costly to bother
One command replaces the design review you would have had to schedule. That changes which decisions are worth exploring at all. The threshold becomes a minute rather than a meeting.
Serial exploration eating afternoons
The specialists run at the same time rather than one after another. Widening the search costs concurrency rather than hours of waiting. That trade is what makes a high role count practical.
One failure sinking everything
A role that fails or exceeds its five-minute bound is reported, and the run continues with what the others produced. A partial slate still beats a single opinion. The run stops only when every role failed.
No control over search width
The role count is a flag from 3 to 100. A routine decision gets three perspectives and a genuinely hard one gets thirty. Breadth is something you choose rather than something you receive.
Comparisons that are not comparable
The model and reasoning-effort flags are forwarded to every turn and every fork in the run. Two approaches are therefore produced under the same conditions. One branch cannot look better just because it happened to think harder.

When to use it

When the decision is more expensive to get wrong than the exploration is to run.
When you suspect the obvious approach is not the best one.
When the change will be hard to reverse once it is in.
When you want to compare blast radius across approaches before choosing.
When the work is worth a design review but not worth scheduling one.
When you are the only person available to disagree with you.
When your team keeps relitigating a decision nobody wrote the reasoning down for.
When you want to see the rejected options, not just the winner.
When you want options generated before anything is allowed to touch your repository.
When you need the exploration to be genuinely parallel rather than a serial afternoon.
When a single agent has already given you an answer you do not trust.
When you want to widen or narrow how hard the search goes with one number.
When the same problem could reasonably be solved four ways and you cannot rank them yet.
When you are starting a piece of work rather than finishing one.
When the approach you would pick first is the one you trust least.
When you want the decision's reasoning written down before the code exists.
When you want the comparison to be repeatable, with the same model and effort across every branch.

Agent environment

Pricing

$0.02 per launch

runtime
local
one-time

Ensemble Agent is a runtime: it runs on your machine, through the Codex CLI you already installed, against your own OpenAI account. Codex is the only supported host, because it is the only one with verified thread forking and a sandbox per fork, which is what keeps the specialists read-only. Vidbyte charges a one-time flat $0.02 per launch, taken only after the CLI has confirmed your task, the SDK, and the host. Your own model spend is the number that actually moves: a three-role run is roughly a dozen Codex sessions on your subscription, and `--roles 100` produces something like a thousand approaches for the selector to read. No repository contents or environment values are sent to Vidbyte with the admission.

Setup is four things: install vidbyte-cli, log in with your Vidbyte key, add balance at the usage page, and store an OpenAI key with `vidbyte-cli provider login openai` so the forks have credentials. The install prompt below makes your own coding agent run those checks in order and only asks you about what is missing. This agent is live today. Start at the default of three roles and raise the count deliberately once you have seen what one run costs on your own account.

Run it from the command line

Every agent starts with the same two setup commands: install vidbyte-cli, then log in with your Vidbyte key. Ensemble Agent also needs an OpenAI key stored for Codex, and then it is one command with a dial for how many specialists to use. Two read-only checks confirm your machine is ready before you launch anything.

```
git clone https://github.com/cerredz/Vidbyte-cli
cd Vidbyte-cli
python -m venv .venv && source .venv/bin/activate
python -m pip install -e ".[dev,codex]"
```
Installs vidbyte-cli, the command line every Vidbyte agent is started and tracked from. It is at version 0.1.0 and is not published to PyPI yet, so it installs from source into a virtual environment rather than with a bare pip install. Run `vidbyte-cli --version` afterwards, and if it prints a version number the install worked and the command is on your PATH.
Subcommands
-e
Installs the package in editable mode, pointing at the folder you cloned instead of copying it somewhere else. A later `git pull` in that folder updates the CLI without a reinstall. This is the install mode the CLI's own README documents.
".[dev,codex]"
Adds the optional extras on top of the base package. The codex extra carries the Vidbyte SDK's Codex integration, which every agent that drives Codex needs, and dev carries the build and lint tools from the README's development install. Git has to be installed, because the SDK revision is fetched from source.
```
vidbyte-cli login
```
Stores your Vidbyte API key, which is what identifies you and what every agent's charge is billed against. It reads the key at a hidden prompt, checks it against Vidbyte before saving anything, and then keeps it in your operating system's keyring. Run `vidbyte-cli whoami` afterwards to confirm which account the stored key belongs to.
Subcommands
--with-token
Reads the key from standard input instead of a hidden prompt, which is how you log in from a script or a CI job. Pipe it in from your secret store rather than typing it into the command. There is deliberately no --api-key flag, because anything in the command line leaks into process listings, shell history, and CI logs.
--allow-file-fallback
Approves storing the key in a permission-restricted file when the machine has no operating-system keyring, such as a bare Linux server. Without it, login asks before falling back, or refuses when there is no terminal to ask on. Anything running as your user can read that file, so use it only where a keyring genuinely is not available.
```
vidbyte-cli provider login openai
```
Stores the OpenAI key that every Codex fork in the run will use, separately from your Vidbyte key. Every specialist runs on that account, so choose it deliberately. The CLI resolves the key from OPENAI_API_KEY first, then from this stored profile.
Subcommands
--with-token
Reads the OpenAI key from standard input instead of a hidden prompt. Use it in scripts and CI, piping the key from your secret store. The key never has to appear in the command line or your shell history.
--allow-file-fallback
Approves storing the key in a permission-restricted file when no operating-system keyring is available. Without it, the command asks first or refuses when it cannot ask. Anything running as your user can read that file.
```
vidbyte-cli runtime same-host-ensemble "<your task>"
```
Runs the whole four-stage sequence on your task in the current working directory: plan the roles, fan out the proposals, narrow to one, and implement it. Everything before the final implementation stage happens in read-only forks. Nothing in your working tree changes until an approach has been chosen.
Subcommands
--roles
Sets how many specialist perspectives the planner invents for this task, from 3 to 100, defaulting to 3. More roles widen the slate the selector has to narrow, which is what you want for a decision that is hard to reverse. Every role runs at the same time in its own fork on your own subscription, so this is the dial that moves your model usage.
--model
Forwards one model choice to every Codex turn and every fork in the run. Set it when you want the comparison between approaches to be like-for-like, or when the default model is not the one you want making an architectural call. Leave it out to use the provider default.
--reasoning-effort
Controls how much thinking each turn does, accepting none, minimal, low, medium, high, or xhigh. Raise it when the task is subtle enough that a fast answer is the wrong answer. Like the model flag, it applies to every turn in the run, so the branches stay comparable.
--idempotency-key
Lets you retry a launch whose outcome you never saw without being charged twice. Reuse the same key and the original admission is recovered rather than a new one purchased. Leave it out and a fresh key is generated for every run.
--host
Names the coding agent that hosts the ensemble, and codex is the only accepted value. Codex is the only host with verified thread forking and a sandbox per fork, which the read-only proposals depend on. The flag keeps scripts explicit and stable as more hosts are added.
```
vidbyte-cli runtime doctor
```
Reports which supported coding-agent hosts this machine actually has. Run it before your first ensemble, so a missing Codex shows up as a diagnostic rather than a failed launch. It is read-only and costs nothing.
```
vidbyte-cli runtime list
```
Lists the runtimes Vidbyte will admit, with the charge for each read from Vidbyte's catalog rather than hard-coded in the CLI. The same-host-ensemble line is the price you will actually pay. Use it to compare this agent against the others before picking one.

Run it from your own agent

Copy prompt

Paste this into the agent you already use and it will ask you what you need, then write the exact Ensemble Agent invocation for your job.

You are helping me write the task text for Vidbyte's Ensemble Agent, which invents several specialist perspectives on my task, has each propose 5 to 10 approaches in a read-only sandbox, narrows them in rounds, and then implements exactly one. Ask me these one at a time and wait for each answer: (1) the decision or change I am facing, stated as a problem rather than as a solution I have already picked, (2) the constraints that any acceptable approach must respect — what cannot change, what has to keep working, what I am optimizing for, (3) how reversible this is, so we can choose a role count, and (4) what a good answer would let me do that I cannot do today. Then give me the exact command including the task text in quotes and a `--roles` value, with one sentence on why that number. Write the task as an open problem, because if I state the solution in the prompt every role will just propose variations on it.

Copy install prompt

Paste this into your own agent and it will check what is already installed and logged in, then walk you through only what is missing.

Set me up to use Vidbyte's Ensemble Agent. Run the checks below yourself, in order, before you ask me anything, and let each result decide the next thing you say. Never ask me to paste an API key into this conversation.

1. Run `vidbyte-cli --version`.
   - If it prints a version, say so in one line and go to step 2.
   - If the command is not found, say: "It looks like vidbyte-cli isn't installed yet. Do you want me to install it for you?"
     - Yes: it is at 0.1.0 and not on PyPI, so install from source: clone https://github.com/cerredz/Vidbyte-cli, create a virtualenv, run `python -m pip install -e ".[dev,codex]"`, then re-run `vidbyte-cli --version`.
     - No: tell me the install is the one thing every agent needs, and stop.

2. Run `vidbyte-cli whoami`.
   - If it prints "Authenticated as", I am logged in. Go to step 3.
   - If it prints "Authentication is required.", ask: "You're not logged in yet. Do you already have a Vidbyte API key?"
     - Yes: ask me to run `vidbyte-cli login` in my own terminal. It takes the key at a hidden prompt and checks it before storing it in my keyring. Re-run `vidbyte-cli whoami` when I say it is done.
     - No: these two steps are browser-only, so give me one link at a time and wait. First https://vidbyte.pro/login, where Google sign-in creates the account. Then https://vidbyte.pro/settings/api, where I create a key that is shown once. Then have me run `vidbyte-cli login` myself.

3. Ask: "Have you already added balance to your Vidbyte account?" The CLI cannot read a balance, so ask rather than guess.
   - No or not sure: send me to https://vidbyte.pro/usage to add balance, and wait for me to confirm.

4. Run `vidbyte-cli runtime doctor`.
   - If the codex line says "not found", say: "Ensemble Agent runs through the Codex CLI and this machine does not have it. Do you want me to install Codex?" Install it only if I say yes.
   - Then run `vidbyte-cli provider whoami openai`. If it fails, say: "Codex needs an OpenAI key and none is stored. Please run `vidbyte-cli provider login openai` in your own terminal, so the key never passes through this conversation." Wait for me, then re-run it.

When every check passes, tell me what each one returned in one short list, then give me this command to start: `vidbyte-cli runtime same-host-ensemble "<your task>" --roles 3`.

Similar agents

Persistent Agent
Pick this one instead when you already know the approach and just need it carried all the way to done.
Open agent page →
Adversarial Team
Pick this one instead when the work already exists and you want it attacked rather than re-planned.
Open agent page →
Stages Agent
Pick this one instead when you already know the phases the work should move through and want them run in a fixed order.
Open agent page →

Agents

One job, one workflow, one deliverable. See how Ensemble Agent compares to the rest of the lineup.

Browse all agents →