Stages Agent

Stages Agent runs a single task through a sequence of phases, and each phase is a completely separate agent with its own configuration. An auditing phase can be read-only, think hard, and be forbidden from touching anything. The implementing phase that follows can be allowed to write, run faster, and carry a different set of standing instructions. The phases no longer share one system prompt, one model, or one sandbox, which is the constraint that makes a single agent bad at multi-phase work. You describe up to 25 stages on the command line, one repeated option per setting, so a whole staged flow is one invocation.

Each stage's agent is discarded the moment its stage ends, and no thread history, tool state, or context crosses a stage boundary. What does cross is the output: in sequential mode a stage's prompt can pull in the previous stage's entire output, and the first stage receives your top-level task instead. You can also run every stage at once, in which case each one sees the top-level task and none of them sees the others. Per stage you choose the model, the reasoning effort, the sandbox, the approval policy, and optional reference material that reaches that stage only.

It does not decide what the phases should be; you do, and the ordering you choose is the part it trusts. A stage can be forced to answer in a fixed JSON shape, so the next stage receives a handoff it can check instead of prose it might misread. When a stage fails, the run either stops with every earlier result intact or records the failure and carries on, and a retry goes to a fresh agent. An offline describe command prints every option a stage accepts, so the whole surface is readable without opening the source.

• runtime
• local
• one-time
• stages
• phased-workflow
• per-stage-config
• per-stage-sandbox
• per-stage-model
• system-prompts
• audit-then-implement
• design-doc-flow
• parallel-reads
• sequential-handoff
• structured-handoff
• output-schemas
• phase-isolation
• pipeline

Use cases

1. 01

   You want an agent to audit a codebase before it implements anything, but the same agent doing both always starts editing halfway through the audit. It notices an easy fix, makes it, and the audit quietly turns into a half-finished implementation. You asked for a complete picture first and got neither a complete picture nor a clean change. Telling it not to edit yet is a request, and requests get broken.

   How the agent solves it

   Make the audit its own stage with a read-only sandbox, and make the implementation a later stage that is allowed to write. The audit stage physically cannot edit, so the phase boundary is enforced by the sandbox rather than by the agent's cooperation. Reference the audit's output in the implementation stage's prompt, so the implementer starts from the finished audit. Give each stage a system prompt that fits its job. The run then produces a complete audit followed by a change built on it.

   What to run

   1. Command

      vidbyte-cli runtime stages run "Harden input validation in the API." --stage-prompt "Audit every route for unvalidated input and list findings." --stage-system-prompt "You are an auditor. Report only." --stage-sandbox read-only --stage-prompt "Fix every finding in: {{previous}}" --stage-system-prompt "You are an implementer." --stage-sandbox workspace-write

   What you get

   A finished audit, then a change built on it, with no edits during the audit.

   • An audit stage that could not change a file even when it spotted a fix.

   • An implementation stage that started from the complete list of findings.

   • A clear record of which stage produced which output.

2. 02

   Your design-doc flow needs deep reasoning at the start and speed at the end. With one agent, you pick one model setting for the whole flow, and it is wrong for one of the phases. Either the design phase is shallow, or the mechanical phases burn time and model usage thinking hard about formatting. There is no setting that suits both.

   How the agent solves it

   Give each stage its own reasoning effort, and its own model if you care which one does the thinking. Set high effort on the design stage and medium or low on the mechanical stages that follow. Each stage is a fresh agent, so the settings never have to compromise between phases. Settings are given by position, so the first effort value applies to the first stage, the second to the second, and so on. You spend deep thinking only where it pays off.

   What to run

   1. Command

      vidbyte-cli runtime stages run "Write and implement a design for rate limiting." --stage-prompt "Design it." --stage-system-prompt "You are a system designer." --stage-effort high --stage-prompt "Implement: {{previous}}" --stage-system-prompt "You are an implementer." --stage-effort medium --stage-prompt "Format and lint the changes." --stage-system-prompt "You tidy code." --stage-effort low

   What you get

   Deep reasoning where it matters and speed everywhere else, in one run.

   • A design stage that thought as hard as the problem deserved.

   • Mechanical stages that did not waste effort on routine work.

   • One invocation you can save and rerun with the same settings.

3. 03

   The standing instructions that make an agent a good reviewer make it a timid implementer. You have been trying to write one system prompt that does both, and the result is mediocre at each. Every edit you make to help one phase hurts the other. The compromise prompt keeps growing and keeps getting worse.

   How the agent solves it

   Give each stage its own system prompt, which is the whole point of staging. The reviewing stage gets instructions to be skeptical and thorough, and the implementing stage gets instructions to be decisive. Neither prompt has to be watered down for the other, because the two stages never share an agent. The system prompt is applied when a stage's agent is built and discarded with it. You can then tune each prompt for its own job without breaking the other.

   What to run

   1. Command

      vidbyte-cli runtime stages run "Improve error handling in the payments module." --stage-name review --stage-prompt "Find every weak error path." --stage-system-prompt "Be skeptical. Assume every error path is wrong until proven." --stage-name implement --stage-prompt "Fix these: {{previous}}" --stage-system-prompt "Be decisive. Make the smallest correct change."

   What you get

   Two focused prompts instead of one compromise.

   • A review stage with instructions written only for reviewing.

   • An implementation stage with instructions written only for implementing.

   • Named stages that make the progress output readable.

4. 04

   You want four independent analyses of the same problem, and you do not want them influencing each other. Asking one agent for four perspectives gets you four paragraphs from the same point of view. Running four chats by hand means copying the task four times and keeping the results straight yourself. You want genuinely separate reads with one command.

   How the agent solves it

   Define four stages and run them in parallel. Every stage sees your top-level task, and none of them sees any other stage's output, so the four reads stay independent. Give each stage a system prompt naming the angle it should take. Parallel runs finish sooner, because the stages run at the same time. Compare the four outputs side by side when the run ends.

   What to run

   1. Command

      vidbyte-cli runtime stages run "Should we move sessions from cookies to tokens?" --parallel --stage-prompt "{{previous}}" --stage-system-prompt "Analyze security." --stage-prompt "{{previous}}" --stage-system-prompt "Analyze performance." --stage-prompt "{{previous}}" --stage-system-prompt "Analyze migration cost." --stage-prompt "{{previous}}" --stage-system-prompt "Analyze user impact."

   What you get

   Four independent reads of one question, produced at the same time.

   • Security, performance, migration, and user-impact analyses that never saw each other.

   • No cross-talk pulling the perspectives toward one view.

   • A single run instead of four chats to keep track of.

5. 05

   A later phase needs a specific spec or file excerpt in front of it, and pasting that into the task pollutes every other phase. The early stages get distracted by material they do not need, and the prompt gets longer for every stage. Leaving it out means the phase that needs it works blind. You want reference material that reaches only the stage it is for.

   How the agent solves it

   Attach the material to the one stage that needs it with the stage context option. It is reference rather than instruction, so it sits beside that stage's prompt without replacing it. It reaches that stage only and never carries forward into the next one. Other stages get no context by passing an empty value in their position. Each phase sees exactly the material it needs.

   What to run

   1. Command

      vidbyte-cli runtime stages run "Add the new invoice fields." --stage-prompt "Plan the change." --stage-system-prompt "You plan." --stage-context "" --stage-prompt "Implement: {{previous}}" --stage-system-prompt "You implement." --stage-context "<the invoice schema excerpt>"

   What you get

   Reference material delivered to the one phase that needs it.

   • An implementation stage with the schema excerpt in front of it.

   • A planning stage left uncluttered by material it does not use.

   • No reference text leaking forward into later stages.

6. 06

   One phase hands its results to the next as prose, and the next phase misreads it. A file list gets parsed wrong, a finding gets skipped, or a caveat buried in a paragraph never makes it across. You only notice when the final result is missing something the earlier phase clearly found. The handoff between phases is the weakest point of the flow.

   How the agent solves it

   Force the handing-off stage to answer in a fixed JSON shape with the output schema option. The next stage then receives a structured handoff it can check mechanically, such as a list of files and a summary. Leave the final stage in free prose, since a person reads it. Run the describe command first to see every option and its accepted values without spending anything. The handoff stops being a place where information gets lost.

   What to run

   1. Command

      vidbyte-cli runtime stages describe

   2. Command

      vidbyte-cli runtime stages run "Remove dead feature flags." --stage-prompt "Find every dead flag." --stage-system-prompt "You find dead code." --stage-output-schema '{"type":"object","properties":{"files":{"type":"array"},"summary":{"type":"string"}}}' --stage-prompt "Remove the flags in: {{previous}}" --stage-system-prompt "You remove code safely." --stage-output-schema ""

   What you get

   A phase handoff the next stage can check instead of interpret.

   • A finding stage that returns a file list and a summary in a fixed shape.

   • A removal stage that works from that list rather than from a paragraph.

   • A final answer in prose for the person reading it.

7. 07

   You need one phase that is allowed to look at everything and another that is allowed to change almost nothing, in the same run. With a single agent, permissions belong to the session, so you either grant broad access to the whole flow or cripple the phase that needs it. Neither is safe for an unattended run. Permissions should belong to the phase, not the session.

   How the agent solves it

   Set the sandbox and the approval policy per stage. A read-only stage with approvals denied cannot act under any circumstances, while a later stage can be allowed to write inside the workspace. The sandbox is enforced by Codex itself, so it is a real boundary rather than a hint to the model. Keep full access for the rare stage that must reach outside the working directory, and never for an unattended run. Permissions become part of each phase's definition.

   What to run

   1. Command

      vidbyte-cli runtime stages run "Upgrade the logging library." --stage-prompt "Survey every logging call." --stage-system-prompt "You survey." --stage-sandbox read-only --stage-approval deny_all --stage-prompt "Upgrade the calls in: {{previous}}" --stage-system-prompt "You upgrade." --stage-sandbox workspace-write --stage-approval auto_review

   What you get

   Permissions scoped to each phase instead of granted to the whole run.

   • A survey stage that could not act even if it wanted to.

   • An upgrade stage allowed to write inside the workspace and nowhere else.

   • An unattended run whose riskiest permissions are confined to one phase.

Agent environment

Stages Agent is a runtime: it runs on your machine through the Codex CLI you already installed, against your own OpenAI account, and no stage prompt or intermediate reply ever reaches Vidbyte. Vidbyte charges a one-time flat $0.01 for the whole run, however many stages it holds, which is the lowest charge in the lineup because there is no Vidbyte-side model cost to reconcile. Every stage's model calls are usage on your own subscription, so a parallel run spends that usage concurrently. The describe command is offline and free.

This agent is not live yet. Vidbyte's admission route for it is live, which is why `vidbyte-cli runtime list` already shows runtime.stages, but the CLI command itself is still in review, so `vidbyte-cli runtime stages` does not exist in the released CLI. Setup is otherwise the same as the other runtimes: 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`. The install prompt below runs those checks and then tries `vidbyte-cli runtime stages describe`, which starts working the day the command merges.

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. Stages Agent also needs an OpenAI key stored for Codex, and then it is a run command whose repeated options describe each stage, plus a free describe command. The stages command is still in review, so the invocations below are the shipping surface and not yet runnable.

• 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 stage's agent will run against, separately from your Vidbyte key. Every stage's model calls are billed to that account. 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 stages describe

  Prints every option a stage accepts, what one occurrence of it configures, and the exact words each closed value set takes. It touches no network, buys no admission, starts no agent, and costs nothing. Read it first if you are building a staged invocation programmatically.

• vidbyte-cli runtime stages run "<the whole job>" --stage-prompt "..." --stage-system-prompt "..."

  Runs every stage of one task, one fresh agent per stage, in the current working directory. The task argument is the top-level statement of what the run is for, and it is what the first stage sees. Every stage option is given once per stage, in stage order, so the first occurrence configures stage one, the second configures stage two, and so on.

  Subcommands

  --stage-prompt

  The turn prompt for one stage, and the option that decides how many stages run: give it three times and three stages run. The token {{previous}} is replaced with the previous stage's output, or with the task for the first stage and in parallel mode. A run accepts between 1 and 25 prompts.

  --stage-system-prompt

  The standing instructions for one stage, given exactly as many times as --stage-prompt. This is where a stage's role lives: what it is for, what it must not do, and what shape its output should take. It is discarded with the stage's agent, so it never leaks into another stage.

  --stage-name

  A short label for one stage, used as the agent's name and in progress lines. Leave it out entirely and stages are named stage-1, stage-2, and so on. Give one per stage or none at all, because a partial list is rejected.

  --stage-model

  The model one stage runs on; leave the option out and every stage uses the model Codex is already configured with. Pass an empty value to keep a single stage on that default while pinning the others. An unrecognized model is not caught until Codex runs it.

  --stage-effort

  How much reasoning one stage spends, accepting none, minimal, low, medium, high, or xhigh, defaulting to medium. Analysis and review stages usually justify high, while mechanical stages rarely do. A misspelled value is rejected before anything runs.

  --stage-sandbox

  How far one stage may reach into the filesystem: read-only, workspace-write, or full-access, defaulting to workspace-write. Codex enforces it, so it is a real boundary rather than a hint. Give read-only to stages that only inspect, audit, or plan.

  --stage-approval

  What one stage does when an action needs approval: auto_review lets Codex review and proceed, and deny_all refuses outright. A staged run never stops to prompt you either way. Pair deny_all with a read-only sandbox for a stage that must not act at all.

  --stage-context

  Turn-scoped reference material for one stage, such as a file excerpt, a schema, or a prior decision. It reaches that stage only and never carries forward. Leave it out and every stage runs with none.

  --stage-output-schema

  A JSON object schema that forces one stage to answer in a fixed shape. Use it when the next consumer is another stage, so the handoff can be checked mechanically. Leave a stage's value empty to let it answer in prose.

  --stage-summary

  How much of its own reasoning one stage reports back: none, auto, concise, or detailed, defaulting to auto. It changes what you read, not what the agent does. Choose detailed when a stage exists to show its reasoning to the next one.

  --stage-personality

  The tone one stage writes in: none, friendly, or pragmatic, defaulting to none. It changes framing only, never capability, sandboxing, or cost. Set it on stages whose output a person will read.

  --stage-image

  One image input for one stage, given as a web URL, a data URL, or a local file path. It travels with that stage's turn only. Use it for a screenshot a review stage must look at.

  --stage-skill

  One Codex skill for one stage, written as NAME=PATH pointing at the skill's directory. The skill is loaded by that stage's agent only. Two stages that need the same skill each need their own occurrence.

  --stage-mention

  One named resource for one stage to read, written as NAME=PATH. It reaches that stage's agent only. Leave it out when the prompt already names everything the stage needs.

  --parallel / --sequential

  Chooses whether every stage runs at once or one after another, defaulting to sequential. Sequential passes each finished output into the next stage's {{previous}}, while parallel gives every stage the task and no sight of the others. Stages that build on each other must run sequentially.

  --stop-on-error / --no-stop-on-error

  Decides what happens the first time a stage runs out of attempts. The default stops the run and keeps every result completed before the failure. The no- form records the failure and starts the next stage anyway.

  --max-retries-per-stage

  Sets how many extra attempts a failed stage gets, from 0 to 3, defaulting to 1. Each retry sends the same prompt to a brand-new agent, which recovers from crashes and timeouts. Every attempt is model usage on your own account.

  --idempotency-key

  Recovers an admission whose response you never saw, so the balance is not charged twice for the same run. Leave it out and a fresh key is generated for every run. Reusing a key does not resume the stages; they run again from the first.

• vidbyte-cli runtime list

  Lists the runtimes Vidbyte will admit, with the charge for each read from Vidbyte's catalog. It already shows runtime.stages, because Vidbyte's half is live. The missing half is the CLI command, so `vidbyte-cli runtime stages describe` is the check that tells you it has shipped.

Run it from your own agent

You are helping me build an invocation for Vidbyte's Stages Agent, which runs one task through up to 25 phases, each a fresh Codex agent with its own system prompt, turn prompt, model, effort, and sandbox. Ask me these one at a time and wait for each answer: (1) the whole job in one sentence, which becomes the top-level task, (2) the phases the work naturally has and what each one is for, (3) for each phase, whether it should be allowed to change files at all, and (4) which phase deserves the most reasoning effort. Then write me the full `vidbyte-cli runtime stages run` command with one `--stage-prompt` and one `--stage-system-prompt` per phase in order, plus per-stage sandbox and effort values, and use `{{previous}}` in a stage prompt wherever that phase should build on the one before it. Write every stage prompt as a complete standalone instruction, because the agent running it has no thread history and has never seen the other stages. Note that the CLI half of this agent is still in review, so the invocation is ready but not yet runnable.

Set me up to use Vidbyte's Stages 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: "Stages 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.

5. Run `vidbyte-cli runtime stages describe`.
   - If the CLI says there is no such command, tell me: "You're set up for Stages Agent. Vidbyte's side is live, but the stages command is still in review and is not in the CLI you have yet, so there is nothing to run today." Then stop, because setup is done and there is nothing to launch yet.

When every check passes, tell me what each one returned in one short list, then give me this command to start: `vidbyte-cli runtime stages run "<the whole job>" --stage-prompt "<stage 1>" --stage-system-prompt "<stage 1 role>"`.

Similar agents

• Task Board

  Pick this one instead when you have a flat list of comparable tasks rather than phases that need different configurations.

  Open agent page →

• Ensemble Agent

  Pick this one instead when the phases you would define are all "propose an approach" and what you actually want is a slate to choose from.

  Open agent page →

• Persistent Agent

  Pick this one instead when the work is a single phase that simply needs to be carried all the way to done.

  Open agent page →