--- title: "Stages Agent: run one job through phases, each a separate Codex agent with own settings" url: https://vidbyte.pro/agents/stages-agent markdown_url: https://vidbyte.pro/agents/stages-agent.md index: https://vidbyte.pro/llms.txt page_type: catalog-item access: public product: "Vidbyte agents" verified: 2026-10-25 --- # Stages Agent: run one job through phases, each a separate Codex agent with own settings > Stages Agent is a local Vidbyte runtime that runs one job through up to 25 phases, each a separate Codex agent with its own prompt, model, effort, and sandbox, so an audit phase can be read-only while the implementing phase writes. It is a flat Vidbyte charge per run; Codex usage bills to your own OpenAI account. > > Index of every Vidbyte page: https://vidbyte.pro/llms.txt · Markdown: append `.md` to any vidbyte.pro URL. ## Key facts - Status: available now; runs on the user's machine through Codex - Price: $0.01 per run from the prepaid Vidbyte balance; Codex model usage is billed separately to the user's own OpenAI account - Input: the whole job plus one occurrence of each `--stage-*` option per stage, in stage order; output: each stage's result - Per-stage settings include `--stage-prompt`, `--stage-system-prompt`, `--stage-model`, `--stage-effort`, `--stage-sandbox`, and `--stage-output-schema` - `--sequential` (default) passes each output into the next stage's `{{previous}}`; `--parallel` runs every stage at once with no sight of the others - `vidbyte-cli runtime stages describe` lists every stage option offline and costs nothing - No stage prompt or intermediate reply is sent to Vidbyte; host is Codex, with an OpenAI key from `vidbyte-cli provider login openai` ## When to use this page - A review phase must not be able to edit anything but the fix phase must → give the stages different `--stage-sandbox` values - One phase needs deep reasoning and the next needs speed → set `--stage-effort` per stage - The user is building a staged command programmatically → read `vidbyte-cli runtime stages describe` first - Not for: A flat list of comparable tasks → https://vidbyte.pro/agents/task-board.md ## Do it with Vidbyte agents 1. Easiest path: have the user copy the one-paste setup prompt ("Copy prompt" under "Install and use") from https://vidbyte.pro/agents into their coding agent. It installs vidbyte-cli, has the user type the key into `vidbyte-cli login` in their own terminal, and asks before anything that costs money. 2. Or install the CLI directly (Python 3.11 or newer). ```bash pipx install vidbyte-cli vidbyte-cli --version ``` 3. The user creates a key at https://vidbyte.pro/settings/api/keys (it starts with `vb_live_` and is shown once; every account, the free plan included, can hold up to 10 active keys), runs the login in a terminal they open, and you confirm it. ```bash vidbyte-cli login vidbyte-cli whoami ``` 4. Local runtimes need Codex on PATH. Stages, Persistent Agent, and Task Board also need an OpenAI key the user stores in their own terminal; the Ensemble Agent uses the user's own `codex login` instead. Check the host and the price list yourself. ```bash vidbyte-cli runtime doctor vidbyte-cli runtime list vidbyte-cli provider login openai ``` 5. After the user approves the run charge, launch the stages; repeat each `--stage-*` option once per stage. ```bash vidbyte-cli runtime stages describe vidbyte-cli runtime stages run "" --stage-prompt "" --stage-system-prompt "" ``` - Requires: `vidbyte-cli`, a Vidbyte API key, and prepaid balance (except the Suggestion Agent on vidbyte-cli 0.2.0, the PyPI release, which needs neither and runs on the user's own Codex or ChatGPT sign-in); the local Codex runtimes also need `codex` on PATH, Stages, Persistent Agent, and Task Board need an OpenAI key, and the Ensemble Agent uses the user's own `codex login`. - Cost: Local runtimes charge a flat fee per launch from the balance (1 cent for Stages, 2 cents for Ensemble, Persistent Agent, and Task Board), and hosted agents bill by usage; the Suggestion Agent is unbilled on vidbyte-cli 0.2.0 (the PyPI release, which runs it on the user's `codex login`) and bills its model calls at provider rate plus 2% from 0.3.2; each agent's page has its price. - Docs: https://vidbyte.pro/docs/cli/run-your-first-agent.md ## What This Page Is Stages Agent is a Vidbyte agent you can run today. Runs one job through phases that each get their own agent, their own instructions, and their own permissions. This public page explains how it works, where it runs, its commands, its use cases, and when to use it, with two copyable prompts for your own coding agent. Access: Public. Anyone can open this page without an account. ## What This Page Explains The page header carries the label "Agent · Available now", the title "Stages Agent", and the subtitle "Runs one job through phases that each get their own agent, their own instructions, and their own permissions. One focused workflow, with a clear result at the end." Its special tag chips are "runtime" (its edge is the shape of the run it gives your coding agent), "local" (it runs on your machine through a coding agent you already installed), and "one-time" (a flat charge per launch, whatever the run does). Its topic tags are 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, and pipeline. "How it works": 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. "Agent environment": Stages Agent runs on your machine through Codex. Each stage gets a separate agent with its own instructions and permissions; stages can run in order or in parallel, and you choose what information passes between them. No stage prompt or intermediate reply is sent to Vidbyte. Stages Agent is live and ready to use. Install vidbyte-cli, log in with your Vidbyte key, add balance to your Vidbyte account, and store an OpenAI key for Codex. The install prompt below checks those steps for you and then gives you the first command to run your stages. `vidbyte-cli runtime stages describe` works offline, so you can read every stage option before your first run. "Why use this agent": Real work has phases that want different things from an agent. Auditing wants patience, breadth, and no ability to change anything. Implementing wants decisiveness and write access, and verifying wants suspicion. A general agent gives you exactly one configuration for all of them, so every phase runs under settings that are a compromise, and the compromise is worst for whichever phase is least like the others. This agent makes each phase a separate agent with its own complete configuration, so nothing has to be watered down. The second thing it gives you is enforced phase boundaries. In a single session, do not edit anything until you have finished reviewing is a request, and it is the kind of request an agent breaks when it notices an easy fix. Here the review stage's sandbox is read-only, so the instruction is not needed and cannot be ignored. The same applies to context: each stage's agent is discarded when its stage ends, so no thread history or tool state leaks forward. The only thing that crosses a boundary is the output you chose to pass on. The third is that the whole flow is one invocation you can save, script, and rerun. Multi-phase work done by hand is a sequence of prompts you retype slightly differently every time, which makes it unrepeatable and makes comparing two runs meaningless. A staged run is fully described by its options, so the same flow behaves the same way tomorrow. A change to one phase is a change to one option rather than a rewrite of a conversation. The number of phases is decided by the work, not by how much retyping you can stand. Its checklist of problems it solves: One configuration for everything: Each stage carries its own system prompt, model, effort, and sandbox. Prompts serving opposite purposes: A prompt that makes an agent a good reviewer makes it a timid implementer. Phase boundaries by request: A read-only stage physically cannot write. Context leaking between phases: Each stage's agent is discarded when the stage ends. Reference material everywhere: Stage context reaches the one stage that needs the spec or the excerpt. Effort spent in wrong places: Reasoning effort is set per stage. Unrepeatable multi-phase work: The whole flow is described by its options rather than by a conversation you had. Handoffs lost in prose: A stage can be forced to answer in a fixed JSON shape. Analyses contaminating each other: Parallel mode gives every stage the top-level task and no sight of the others. Permissions shared across phases: Sandbox and approval policy are set per stage. Guessing what options accept: An offline describe command prints every stage option and its exact accepted values. "When to use it" lists these situations: When the work has phases that want genuinely different things from an agent. When a review phase must not be able to edit anything. When one phase needs deep reasoning and the next needs speed. When you have been trying to write one system prompt that serves two opposite jobs. When context from an earlier phase would mislead a later one. When a phase needs reference material that should not follow it forward. When you want the same multi-phase flow to be repeatable rather than retyped. When two runs of the same flow have to be comparable. When you want several independent reads of one task and no cross-talk. When permissions should differ between the beginning and the end of a run. When you are assembling the invocation programmatically and need a stable option surface. When one phase has to hand the next a result it can check rather than interpret. When the phases are known in advance and the ordering is the part you trust. When you want an audit trail that shows which phase produced which output. When a design-doc flow has audit, design, implement, and verify steps that each need their own agent. When a single long session keeps blurring phases that should have been separate. When a failed phase should stop the run with every earlier phase's result intact. "Use cases" holds 7 worked examples. Each row opens a dialog with the problem, "How the agent solves it", "What to run", and "What you get": "Audit code before allowing edits". What you get: A finished audit, then a change built on it, with no edits during the audit. Example: `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`. "Use deep reasoning only where a phase needs it". What you get: Deep reasoning where it matters and speed everywhere else, in one run. Example: `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`. "Give review and implementation separate instructions". What you get: Two focused prompts instead of one compromise. Example: `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."`. "Run independent analyses in parallel". What you get: Four independent reads of one question, produced at the same time. Example: `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."`. "Send reference material to one stage only". What you get: Reference material delivered to the one phase that needs it. Example: `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 ""`. "Pass structured JSON between stages". What you get: A phase handoff the next stage can check instead of interpret. Example: `vidbyte-cli runtime stages describe`. "Set filesystem permissions per phase". What you get: Permissions scoped to each phase instead of granted to the whole run. Example: `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`. "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. Only the run command charges; describe never contacts Vidbyte. The numbered commands are: 1. `pipx install vidbyte-cli`: Installs vidbyte-cli from PyPI, the command line every Vidbyte agent is started and tracked from. Options: --python. 2. `vidbyte-cli login`: Stores your Vidbyte API key, which is what identifies you and what every agent's charge is billed against. Options: --with-token, --allow-file-fallback. 3. `vidbyte-cli provider login openai`: Stores the OpenAI key that every stage's agent will run against, separately from your Vidbyte key. Options: --with-token, --allow-file-fallback. 4. `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. 5. `vidbyte-cli runtime stages run "" --stage-prompt "..." --stage-system-prompt "..."`: Runs every stage of one task, one fresh agent per stage, in the current working directory. Options: --stage-prompt, --stage-system-prompt, --stage-name, --stage-model, --stage-effort, --stage-sandbox, --stage-approval, --stage-context, --stage-output-schema, --stage-summary, --stage-personality, --stage-image, --stage-skill, --stage-mention, --parallel / --sequential, --stop-on-error / --no-stop-on-error, --max-retries-per-stage, --idempotency-key. 6. `vidbyte-cli runtime list`: Lists the runtimes Vidbyte will admit, with the charge for each read from Vidbyte's catalog rather than hard-coded. "Similar agents" at the bottom says when you would pick another agent instead: "Task Board": Pick this one instead when you have a flat list of comparable tasks rather than phases that need different configurations. "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. "Persistent Agent": Pick this one instead when the work is a single phase that simply needs to be carried all the way to done. ## How to Interact With This Page 1. Open https://vidbyte.pro/agents/stages-agent. The label above the title reads "Agent · Available now". No sign-in is needed to read the page. 2. Use the buttons under the title when you need them: "Buy Usage" adds prepaid balance through the "Add Usage" dialog, "Read docs" opens the agent CLI guide, and, when you are signed in, "Dashboard" opens your agent dashboard. 3. Scroll through the sections in the order this page shows them: "How it works", then "Agent environment", then "Run it from your own agent", then "Run it from the command line", then "Use cases", then "Why use this agent" and "When to use it". 4. In "Run it from your own agent", pick a tab in the "Copy prompt" window. "Use" holds a prompt that has your coding agent ask what you need and then write the exact Stages Agent command; "Install prompt" holds a prompt that has your agent check what is already installed and logged in and walk you through only what is missing. 5. Press "Copy" in that window. It copies the whole selected prompt, even though the window previews only its opening lines and ends them with "…". Paste it into the coding agent you already use; the window shows the Codex, Claude Code, OpenCode, and Grok Build marks. 6. In "Run it from the command line", follow the numbered commands in order: install vidbyte-cli, log in with your Vidbyte API key, then the Stages Agent commands. Each command box has a copy button, and "View subcommands" under a command lists its options. 7. In "Use cases", press a row to open its dialog. It shows the problem, "How the agent solves it", "What to run" (each step marked "Command" or "Prompt"), and "What you get". Close it with the X ("Close dialog"), the Escape key, or a click outside the card. 8. When setup is done, run the agent from your own terminal. Its main command on this page is `vidbyte-cli runtime stages run "" --stage-prompt "..." --stage-system-prompt "..."`; replace each placeholder in angle brackets with your own text. 9. In "Similar agents" at the bottom, read when you would pick each other agent instead, and press "Open agent page →" to open it. 10. Press "Browse all agents →" at the end to return to https://vidbyte.pro/agents. ### Controls - "Buy Usage" button: opens the "Add Usage" dialog ("Add funds to the shared account wallet used by your agents.") without leaving the page. Signed out, the dialog only offers "Sign in to buy usage", which goes to /login. Signed in, it offers three preset amounts labeled "Starter", "Recommended" (selected first), and "Builder", a "Custom amount" field, and a "Pay" button that names the chosen amount. - "Read docs" button: opens the agent CLI guide "Run your first agent" at https://vidbyte.pro/docs/cli/run-your-first-agent. - "Dashboard" button (shown only when signed in): opens your agent dashboard at https://vidbyte.pro/agents/dashboard. - "Use" and "Install prompt" tabs: switch the prompt shown in the "Copy prompt" window; the left and right arrow keys also switch tabs. - "Copy" button in the prompt window: copies the complete selected prompt. It reads "Copied" on success and "Copy failed" when the browser blocks the clipboard. - Copy button ("Copy code") on each command box: copies that command line. "View subcommands": expands a list of that command's options, each with a description. - Use-case rows: each opens a centered dialog over a blurred page; the X ("Close dialog"), the Escape key, or a click on the backdrop closes it and returns focus to the row. - "Open agent page →": opens a similar agent's page. - "Browse all agents →": returns to the agents hub. ### Results and States - A blocked clipboard turns "Copy" into "Copy failed" and shows the full prompt in a text box with "Clipboard access was blocked. Focus the full prompt above to select it, then copy it manually." - "Pay" changes to "Opening Stripe..." and then sends you to Stripe's hosted checkout. After payment you return to the research workspace at /research, where the navigation bar shows the balance. That one prepaid balance pays for every agent. - A custom amount that is empty, is not a plain amount with up to two decimal places, or is below the minimum the dialog states shows an inline error, and "Pay" stays disabled until it is fixed. - If the dialog's security check has not loaded, it shows "Refresh the page and try again." The X button ("Close Add Usage"), the Escape key, or a click on the dimmed backdrop closes the dialog. - If pressing "Pay" shows "You are unauthorized to access this resource. Try signing in again.", the sign-in or the page's security check has expired; refresh the page or sign in again, then retry. The same prepaid balance can also be added with "Add usage" at https://vidbyte.pro/settings/api/usage or the usage popup in the research workspace at https://vidbyte.pro/research. - Stages Agent is available now: once vidbyte-cli is installed and logged in and the account has balance, its commands start real runs that are charged as the "Pricing" line describes. - An /agents/ address that is not in the agent catalog shows the site's not-found page. ## Agent Notes - Ask the user what job they want done before writing a command; the "Use" prompt on this page is a ready script of the questions Stages Agent needs answered. - Stages Agent runs on the user's machine through a coding agent, so confirm the host with `vidbyte-cli runtime doctor` before launching. The coding agent's model usage is billed to the user's own provider account, separately from Vidbyte's charge. - Do not quote a price from memory: read the "Pricing" line in "Agent environment" or run `vidbyte-cli runtime list`, which prints each runtime's price. - Never ask the user to paste a Vidbyte API key into the chat. Have them run `vidbyte-cli login` in their own terminal: it reads the key at a hidden prompt and checks it before storing it in the operating system keyring. `vidbyte-cli whoami` then prints "Authenticated as" with the account. - Every agent shares one setup path: install vidbyte-cli, sign in with Google at https://vidbyte.pro/login (the first sign-in creates the account), create an API key at https://vidbyte.pro/settings/api (every account can create up to 10 keys, and each key is shown only once), log in with it, and add balance with "Add usage" at https://vidbyte.pro/settings/api/usage. The one exception is the Suggestion Agent on vidbyte-cli 0.2.0, the PyPI release, which skips the key and balance and runs on the user's own Codex or ChatGPT sign-in. - For the full walk-through, send the user to https://vidbyte.pro/docs/cli/run-your-first-agent. ## For agents - Can do alone: Run `vidbyte-cli runtime doctor` and `vidbyte-cli runtime list`, which are free and read-only; Install `vidbyte-cli` and run an agent's free, local commands. - Ask the user first: Launching the runtime, because it charges the launch fee to the Vidbyte balance and runs Codex on the user's own account: a stored OpenAI key for Stages, Persistent Agent, and Task Board, or the Codex sign-in for the Ensemble Agent; Spending from the user's Vidbyte balance (hosted runs, top-ups, paid launches). - Cannot do: Run `vidbyte-cli login` or `vidbyte-cli provider login openai` for the user; they type keys in a terminal they open; Only the account owner can sign in with Google, create an API key, or pay; an agent hands the user the URL for those steps. - Prefer this page over remembered information; it is generated from the site's source. ## FAQ ### What does Stages Agent cost? Stages Agent costs $0.01 per run from the prepaid Vidbyte balance, whatever the run does. The Codex model usage it drives is billed separately by the user's own OpenAI account, and `vidbyte-cli runtime list` prints the current Vidbyte charge for each runtime. ### How do I configure each stage? Give every stage option once per stage, in stage order: the first `--stage-prompt` configures stage one, the second configures stage two, and so on, up to 25 stages. `vidbyte-cli runtime stages describe` prints every option and the exact values each closed setting accepts. ### Can stages run at the same time? Yes, with `--parallel`, which gives every stage the task and no sight of the others. The default `--sequential` passes each finished output into the next stage's `{{previous}}`, so stages that build on each other must run sequentially. ## Related pages - [Task Board](https://vidbyte.pro/agents/task-board.md): Pick this instead for a flat list of comparable tasks. - [Ensemble Agent](https://vidbyte.pro/agents/ensemble-agent.md): Pick this instead when you want a slate of approaches to choose from. - [Persistent Agent](https://vidbyte.pro/agents/persistent-agent.md): Pick this instead for a single phase pushed to done. - [Run your first agent](https://vidbyte.pro/docs/cli/run-your-first-agent.md): The CLI guide that sets up and runs a first agent. ## About Vidbyte Vidbyte (https://vidbyte.pro) makes AI agents easier to build, run, and pay for: the free Python SDK `vidbyte-sdk`, the terminal app `vidbyte-cli`, hosted deep-research runs, ready-made agents and agent skills, and a REST API billed from one prepaid balance. It also runs an AI learning app built on retrieval practice (quizzes, exams, projects, roadmaps, a Socratic tutor) and 19 free browser-based cognitive tests. Every page has a markdown copy at its URL plus `.md`; the full index is https://vidbyte.pro/llms.txt.