Suggestion Agent

How it works

The Suggestion Agent looks at where you are and tells you what to do next, before you have worked it out yourself. You give it one goal in any field, whether that is a codebase, a thesis, a launch, a job search, or a shop, along with whatever you know: what is done, what is in progress, what you decided, what you must not touch, and what worries you. It drafts a wide pool of candidate next actions across 31 kinds of opportunity, from the quick win you walked past and the thing you should stop doing to the bet that could reshape the whole plan. An independent critic reviews that pool against your goal, throws out the weak, the vague, and the redundant, and sends the rest back to be sharpened. That review-and-revise cycle repeats for as many rounds as you allow, and only then are the strongest ideas ranked.

What comes back is a short, ranked slate of next actions rather than a brainstorm. Every idea says why it matters now, what it should earn you, the first step to take, the steps after that, the decisions it forces, the assumptions it rests on, and how you will know it is finished. Each one is labeled with an effort estimate, a horizon of now, next, or later, and whether it is ready to start or first needs evidence, a decision, or an unblocked dependency, so a five-minute fix and a year-long direction can sit side by side. Ideas point back to the exact notes, files, and facts you supplied, and an idea that cites something you never gave it is dropped before you see it. Any single idea can be pulled out as a self-contained packet and handed to a person or another agent to carry out, and a project remembers which ideas you accepted and rejected, so the next slate starts from your judgment instead of from zero.

The Suggestion Agent thinks and recommends, and it stops there. Its agents run read-only, so they cannot edit a file, run a command, or change anything in your project. It does not start work you have not chosen, and a handoff packet grants nobody permission to act. When the evidence does not support more ideas, it returns fewer and says so instead of padding the list. When the goal is too ambiguous to act on, it stops and asks you one precise question instead of guessing.

• harness
• local
• one-time
• next-action
• proactive
• evidence-grounded
• independent-critic
• ranked-ideas
• idea-categories
• handoff-packets
• project-memory
• feedback-loop
• decision-support
• quick-wins
• big-bets
• strategy
• any-domain

Agent environment

The Suggestion Agent runs on your machine through the Codex CLI you installed, against your own OpenAI account, with every Codex agent in a read-only sandbox. Your goal, your context, and the ideas travel between Codex and OpenAI under your account; Vidbyte receives only the admission itself, which names the host and how many blocks of suggestions you bought. Vidbyte charges a flat $0.02 for every block of up to 10 requested suggestions, so a run of 2 to 10 suggestions costs $0.02 and a run of 11 to 15 costs $0.04, whatever categories you pick. Model usage is a separate cost billed to your OpenAI account, and more review rounds or extra compute raise that half rather than Vidbyte's. The charge is taken after the CLI has checked your request, the SDK, and that Codex is installed, but before the first model call, so store your OpenAI key before a real run. A dry run, the category list, handoffs, projects, and feedback never call a model and are never charged.

The Suggestion Agent is live today. 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` for Codex to run on. Codex is the only supported host for this agent. The install prompt below makes your own coding agent check each of those in order, asks you only about the ones that are missing, and then gives you the first command to run. If a run's reply is lost after it was charged, rerunning with the same `--idempotency-key` recovers that purchase instead of paying again.

Run it from the command line

Install vidbyte-cli, log in with your Vidbyte key, and store an OpenAI key for Codex. Then run the agent with one goal and whatever context you have, and use the smaller commands to browse categories, hand ideas off, and keep project memory.

1. 01
   bash

   Copy

   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.

   View 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.

2. 02
   bash

   Copy

   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.

   View 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.

3. 03
   bash

   Copy

   vidbyte-cli provider login openai

   Stores the OpenAI key that the Suggestion Agent's generator and critic run against, separately from your Vidbyte key. Every generation, critique, and revision turn is billed to that account. The CLI resolves the key from OPENAI_API_KEY first, then from this stored profile.

   View 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.

4. 04
   bash

   Copy

   vidbyte-cli agents suggest run --goal "<goal>"

   Generates, critiques, and ranks next actions for one goal, and prints the slate. The goal is the only required input; every other option adds context, narrows the search, or sets a limit. All of it is checked before any model is called, so a mistake fails for free.

   View subcommands

   --goal

   States the one outcome you want the next actions to move toward, in up to 4,096 characters. It is required for every run. A specific goal, such as a date or a measurable result, produces far more specific ideas than a broad one.

   --project

   Loads the stored memory of one project, created earlier with project create, as context for this run. That memory is the project's title, its scope, and every suggestion you accepted or rejected with the reasons. Leave it out and the run reads no project file at all.

   --context

   Adds a background fact that does not fit a more specific option. Repeat it once per fact. Each value is carried to the agents as task data, never as an instruction.

   --files

   Adds a text, Markdown, or JSON file whose contents inform the run, repeated once per file. Only the paths you name are read; nothing else on disk is scanned. Oversized files are truncated and reported in the manifest rather than dropped silently.

   --attach

   Attaches one local file directly to the agents' input, repeated once per file in order. Text files are sent as snapshots and supported images stay native images. Missing, duplicate, empty, unsupported, or oversized files fail before anything is charged.

   --completed

   Records an outcome that is already true, so the agent does not propose it again. Repeat it once per finished item. This is the single most effective way to stop a slate from repeating work you already did.

   --in-progress

   Records work that has started but is not finished. The agent treats it as underway, so it can suggest how to finish or unblock it rather than proposing it as new. Repeat it once per item.

   --decision

   Records a decision already made, so ideas build on it instead of reopening it. Repeat it once per decision. Use it for settled choices, such as a vendor, a deadline, or an architecture.

   --constraint

   Records a hard limit every idea must respect, such as a budget, a team size, or a freeze. Repeat it once per constraint. Every idea is expected to respect it, and the independent critic reviews each idea against it.

   --avoid

   Names a direction you do not want proposed at all. Repeat it once per direction. It is softer than a forbidden action: it steers the search away rather than declaring something off limits.

   --mistakes

   Records a mistake already made, so the agent can suggest how to recover and avoid proposing a repeat. Repeat it once per mistake. Use it for errors that shaped where the work is now.

   --forbidden

   Declares an action that must never appear in a suggestion, such as deleting data or contacting customers. Repeat it once per action. Use it for anything that would be unacceptable, not merely unwanted.

   --approaches

   Records an approach you already tried or are considering, so the agent can compare against it or build on it. Repeat it once per approach. It keeps the slate from rediscovering what you already know.

   --outcomes

   Records a result you have already observed, such as a metric after a change. Repeat it once per outcome. Real outcomes let the agent judge what is working instead of guessing.

   --blockers

   Names something currently stopping progress. Repeat it once per blocker. Naming it points the agent at ideas that remove it.

   --hypotheses

   Records a belief you have not yet tested. Repeat it once per hypothesis. The agent can propose the cheapest way to confirm or kill each one.

   --risks

   Names a risk you already see. Repeat it once per risk. The agent can propose ways to reduce it, and spends less of the slate re-discovering it.

   --trajectory

   Describes the direction the work has been moving over time, such as a trend or the last few milestones. Repeat it once per note. It helps the agent tell a next step apart from a course correction.

   --question

   States an open question you want the ideas to help answer. Repeat it once per question. The agent treats each one as something worth resolving, not just as background.

   --capability

   Names a skill, tool, person, access grant, or resource available to you. Repeat it once per capability. Ideas can then use what you have instead of assuming you have nothing.

   --success

   States what success looks like for the goal. Repeat it once per criterion. The critic uses it to judge whether an idea actually moves you toward the finish line.

   --count

   Sets the most ideas the final slate may hold, from 2 to 15, defaulting to 5. It is a ceiling, not a quota, so a weaker field returns fewer ideas with a shortfall note. It is also the number the Vidbyte charge is based on, in blocks of up to ten.

   --category

   Limits the search to one kind of opportunity, such as quick_wins, big_bets, risk_prevention, or strategy, repeated once per category. There are 31 categories, and unknown names are rejected before any model is called. Leave it out to consider the whole registry.

   --all-categories

   Explicitly asks for every category to be considered. This matches the behavior when no category is given, but records the intent in the saved request. It does not force one idea from each category.

   --horizon

   Chooses when ideas should become useful: now, next, later, or any, which is the default. Now keeps every idea to something you can start today, while later favors directions that pay off over time. Each idea still records its own horizon in the result.

   --rounds

   Sets how many critique-and-revision cycles refine the pool, from 1 to 8, defaulting to 2. More rounds help difficult or ambitious goals, and every round adds model usage on your own account. The run ends early if a revision leaves no candidates.

   --max-messages

   Caps how many times a critic may stop its review early and message the generator directly about one urgent problem, from 0 to 8, defaulting to 2. Once the limit is spent, critics always return a full review. Zero turns the messages off.

   --provider

   Names the model service that powers the generator and critic. The only accepted value is openai, and leaving it out keeps the default provider. It makes the source of a run's reasoning explicit in scripts.

   --critic-model

   Names a different model for the independent critic only, leaving the generator on its default. Use it when you want review from a stronger or different model than the one drafting ideas. Leave it out to use the default for both.

   --extra-compute

   Runs one separate generator for each selected category and combines their ideas before critique. It finds more genuinely distinct directions, at the cost of more model turns and more time. The Vidbyte charge is the same with or without it.

   --max-output-tokens

   Bounds the size of each individual model reply, from 1 to 5,000,000 tokens. It keeps one turn from consuming the whole budget. It is a target for each reply, not a billing guarantee.

   --max-total-tokens

   Bounds the token usage of the whole run, from 1 to 20,000,000 tokens. When the budget is reached, the run stops and returns the last fully reviewed ideas. The result names the stop reason so a partial slate never looks complete.

   --timeout-seconds

   Sets a deadline for the whole run, from 1 second to 86,400 seconds. No new work starts after it passes, and the last fully reviewed ideas are returned. A request already in flight may finish slightly later.

   --dry-run

   Validates the whole request and prints its settings and context manifest without calling a model. It needs no provider key and is never charged. Use it to confirm what a large request will read before you run it.

   --idempotency-key

   Lets you retry a run whose charge went through but whose reply never reached you, without paying twice. Leave it out and a fresh key is generated for every run. Reusing a key recovers the purchase only; the ideas are generated again.

5. 05
   bash

   Copy

   vidbyte-cli agents suggest categories

   Lists the 31 categories the agent searches across, with a one-line summary of each. Use it to pick the right values for the category option. It never calls a model and needs no login.

   View subcommands

   --view-all

   Prints the summary list of every category, which is also the default output. It cannot be combined with the single-category view.

   --view

   Prints the full definition of one category, including the guidance the generator follows for it. Use it to understand exactly what a category will and will not produce before you select it.

6. 06
   bash

   Copy

   vidbyte-cli agents suggest handoff --input <result.json> --idea <idea-id>

   Extracts one idea from a saved result as a self-contained packet with its evidence and a copyable execution prompt. Save the result first by running with the JSON output option and redirecting it to a file. It reads the file locally, never calls a model, and grants nobody permission to act.

   View subcommands

   --input

   Points at the saved JSON result of an earlier run. The file is validated before any idea is selected. A file that is not a valid suggestion result fails with a clear error.

   --idea

   Names the exact idea to extract by its identifier, such as idea-003. A title, a prefix, or a close match is never accepted in its place. Copy the identifier from the result you saved.

7. 07
   bash

   Copy

   vidbyte-cli agents suggest project create --key <key> --title "<title>" --description "<scope>"

   Creates a local project that remembers your reactions to suggestions about one body of work. Create it once, then pass its key to every run about that work. It is stored only on your machine and never calls a model.

   View subcommands

   --key

   Sets the project's stable key: 1 to 64 lowercase letters, numbers, hyphens, or underscores, starting with a letter or number. Every later run and feedback call uses this key.

   --title

   Gives the project a short human-readable name. The generator reads it so it knows what body of work your feedback belongs to.

   --description

   Describes the project's scope in a sentence or two. A clear scope stops feedback about one area from misleading suggestions about another.

8. 08
   bash

   Copy

   vidbyte-cli agents suggest project list

   Lists every local project with its key, title, and description. Use it to recover a key in a new session. It opens no feedback file and never calls a model.

9. 09
   bash

   Copy

   vidbyte-cli agents suggest feedback accept --project <key> --suggestion "<idea>"

   Records that you clearly wanted a suggestion, so later runs lean toward ideas like it. Use feedback reject with the same options to record a suggestion you clearly refused. Both append to the project's history, and neither calls a model.

   View subcommands

   --project

   Names the project the reaction belongs to by its key. The project must already exist; feedback never creates one.

   --suggestion

   Gives the text of the suggestion you are reacting to. A rejected suggestion that later reappears word for word is removed before ranking.

   --reason

   Explains why you accepted or rejected it. It is optional, but the reason tells the next run which quality mattered, not just which idea.

Use cases

Each example names the problem, the setup, the command to run, and the result you should expect.

1. Find the next step when you are stuck
2. See the big move before the quarter starts
3. Get unstuck in a field outside software
4. Let your coding agent see ahead mid-task
5. Stop hearing the same rejected idea
6. Map every direction before choosing one
7. Catch the risk before you ship
8. Change course in a job search
9. Grow a small business past a plateau

Run it from your own agent

You are helping me use Vidbyte's Suggestion Agent, which sees the next optimal action on a goal in any field before I do and returns a short, reviewed, ranked slate. Ask me these one at a time and wait for each answer: (1) the one goal I want to move forward, as specifically as I can state it, ideally with a number or a date, (2) what is already done, what is in progress, what I have already decided, and any results I have already seen, (3) any hard constraints, directions to avoid, and risks I already see, (4) any notes or files the ideas should be grounded in, and (5) whether I want something to do today, the next move, or a longer-term direction, and whether small wins or big bets matter more right now. Then write me the exact `vidbyte-cli agents suggest run` command, using --completed, --in-progress, --decision, --outcomes, --constraint, --avoid, --risks, --files, --horizon, --category, and --count only where my answers justify them. Run `vidbyte-cli agents suggest categories` first if you need the exact category names, and give one sentence of reasoning for each option you chose.

Set me up to use Vidbyte's Suggestion 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: "Suggestion 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 agents suggest run --goal "<the goal you want to move forward>" --count 5`.