vidbyte-cli 0.1.0__tar.gz → 0.3.3__tar.gz

vidbyte_cli-0.3.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vidbyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vidbyte_cli-0.3.3/PKG-INFO

@@ -0,0 +1,619 @@
+Metadata-Version: 2.4
+Name: vidbyte-cli
+Version: 0.3.3
+Summary: Vidbyte CLI: start hosted Research harness runs, run local Codex coding-agent teams, and get ranked next actions from your terminal.
+Author-email: Vidbyte <contact@vidbyte.pro>
+License-Expression: MIT
+Project-URL: Homepage, https://vidbyte.pro
+Project-URL: Documentation, https://vidbyte.pro/docs/cli
+Project-URL: Repository, https://github.com/cerredz/vidbyte-cli
+Project-URL: Issues, https://github.com/cerredz/vidbyte-cli/issues
+Project-URL: Changelog, https://vidbyte.pro/changelog
+Project-URL: Research harness, https://vidbyte.pro/docs/harnesses/research
+Project-URL: Agent skills, https://vidbyte.pro/docs/cli/agent-skills
+Keywords: vidbyte,cli,research,ai-agents,codex,terminal,claude-code,agent-skills,mcp,mcp-server,deep-research,coding-agents,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: keyring<26,>=25.2
+Requires-Dist: platformdirs<5,>=4.4
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: PyNaCl<2,>=1.5
+Requires-Dist: rich<16,>=13.7
+Requires-Dist: x402[evm]==2.8.0
+Requires-Dist: vidbyte-sdk[codex]<0.5,>=0.4.1
+Provides-Extra: codex
+Requires-Dist: vidbyte-sdk[codex]<0.5,>=0.4.1; extra == "codex"
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: build==1.5.0; extra == "dev"
+Requires-Dist: mcp<3,>=2.3; extra == "dev"
+Requires-Dist: mypy==2.3.0; extra == "dev"
+Requires-Dist: ruff==0.16.0; extra == "dev"
+Requires-Dist: twine==6.2.0; extra == "dev"
+Dynamic: license-file
+
+# Vidbyte CLI
+
+Vidbyte CLI: start hosted Research harness runs, run local Codex coding-agent teams, and get ranked next actions from your terminal.
+
+`vidbyte-cli` is Vidbyte's terminal app for AI-agent work. It starts hosted, persistent
+research runs on Vidbyte's servers (the
+[Vidbyte Research harness](https://vidbyte.pro/docs/harnesses/research), whose agent is the
+Persistent Researcher), runs teams of local Codex coding agents on your machine (Ensemble
+Agent, Persistent Agent, Task Board, Stages Agent), and turns a goal into ranked,
+critic-reviewed next actions (Suggestion Agent). Its commands print JSON with `--json`, so
+Claude Code and Codex can drive it, and the agent skills (`npx skills add cerredz/vidbyte-cli`,
+<https://vidbyte.pro/docs/cli/agent-skills>) teach them how. The CLI is free and MIT-licensed.
+Hosted runs and local launch fees are paid from one prepaid Vidbyte API balance; local agents
+run their models on your own Codex or OpenAI account. Docs: <https://vidbyte.pro/docs/cli>.
+
+## Install
+
+`vidbyte-cli` is published on PyPI and requires Python 3.11 or newer.
+
+```bash
+python -m pip install vidbyte-cli                  # into an activated virtual environment
+pipx install vidbyte-cli                           # or: a global command in its own environment
+pipx upgrade vidbyte-cli                           # move an existing pipx install to the latest release
+vidbyte-cli --help
+```
+
+The step-by-step guide lives at <https://vidbyte.pro/docs/cli/quickstart>.
+
+## Log in
+
+Create an API key at <https://vidbyte.pro/settings/api>, then run:
+
+```bash
+vidbyte-cli login                                  # guided: shows where to get a key, then a hidden prompt
+printf '%s' "$VIDBYTE_KEY" | vidbyte-cli login --with-token   # scripts and CI: no prompt, no styling
+```
+
+The interactive prompt is styled with [Rich](https://github.com/Textualize/rich) and written
+to stderr, so stdout still carries only the one result line. `--color never`, `NO_COLOR`, and
+`TERM=dumb` keep it plain. `vidbyte-cli provider login <provider>` follows the same pattern.
+
+If the CLI is useful to you, star it on GitHub from your terminal:
+
+```bash
+vidbyte-cli star              # stars through the GitHub CLI (gh) when it is logged in
+vidbyte-cli star --browser    # or open https://github.com/cerredz/vidbyte-cli and click Star
+```
+
+Bugs and feature requests go to <https://github.com/cerredz/vidbyte-cli/issues>.
+
+## Install (development)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate                          # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
+vidbyte-cli --help
+```
+
+The console command is `vidbyte-cli`. The reusable Python entry function returns an integer
+status; only the generated console wrapper and `python -m vidbyte_cli` terminate a process.
+
+## Global options
+
+Root options precede the command: `vidbyte-cli --format json --profile work research threads`.
+
+| Option | Behavior |
+| --- | --- |
+| `--format human\|json\|jsonl\|none` | Human, one-document, streaming, or suppressed results |
+| `--json` | Alias for `--format json`; conflicts with any other `--format` value |
+| `--profile NAME` | Select a configuration and credential scope |
+| `--no-input` | Never prompt for interactive input |
+| `--color auto\|always\|never` | Color preference, subject to terminal safety |
+| `--debug` | Show redacted stack frames — never exception values, causes, or locals |
+
+Results are the only thing written to stdout; progress, warnings, diagnostics, and errors go
+to stderr. JSON and JSONL records carry `schema_version` and `kind`, and machine errors use
+that same envelope.
+
+Every error also carries `description`, `trace`, and `file_path` — non-sensitive fields that
+let an agent calling this CLI diagnose and correct its own invocation.
+
+A document printed by a recorded agent run also carries a top-level `run_id`, the id that
+`vidbyte-cli runs show` takes, beside `schema_version` and `kind`; it is never inside `data`,
+which stays the command's own. Documents from any other command have no `run_id` key.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `vidbyte-cli login` / `logout` / `whoami` | Manage the stored Vidbyte API key |
+| `vidbyte-cli billing balance` | Show the spendable, available, and held Vidbyte API balance (free, never pays) |
+| `vidbyte-cli billing top-up --confirm [--idempotency-key KEY]` | Add the $5.00 minimum API-balance credit through x402 (paid; needs the owner's approval) |
+| `vidbyte-cli research start <prompt>` | Open a research thread and admit its first run |
+| `vidbyte-cli research add <thread_id> <prompt>` | Add another run to an existing thread |
+| `vidbyte-cli research resume <run_id>` | Continue a partial, failed, or out-of-credit run |
+| `vidbyte-cli research status <run_id>` | Show one run's current status |
+| `vidbyte-cli research watch <run_id>` | Follow one run until it settles |
+| `vidbyte-cli research threads` | List your research threads |
+| `vidbyte-cli research thread <thread_id>` | Show one thread and its rollup counters |
+| `vidbyte-cli runtime list` | List local runtime primitives and admission prices |
+| `vidbyte-cli runtime doctor` | Detect supported native coding-agent hosts |
+| `vidbyte-cli runtime adversarial-team <task>` | Planned: checks the launch, then stops before any charge |
+| `vidbyte-cli runtime same-host-ensemble <task>` | Run a role-differentiated agent ensemble on this machine |
+| `vidbyte-cli runtime persistence <task> [--strength 1-6]` | Run one Codex session with 6–100 additional improvement turns |
+| `vidbyte-cli agents list` | List runnable agent workflows and describe what each does |
+| `vidbyte-cli runs list [--all] [--agent ID] [--limit N]` | List the agent runs still going on this machine (offline, free) |
+| `vidbyte-cli runs show <run_id>` | Show one recorded run's request and output (offline, free) |
+| `vidbyte-cli runs last [--agent ID]` | Show the newest recorded agent run (offline, free) |
+| `vidbyte-cli mcp serve [--workspace PATH]` | Local MCP server that routes a request to one Vidbyte agent (needs the `mcp` extra) |
+| `vidbyte-cli config get\|set` | Manage CLI configuration |
+| `vidbyte-cli doctor` | Diagnose CLI setup |
+| `vidbyte-cli setup-prompt` | Print a detailed, permission-first install prompt for a coding agent |
+| `vidbyte-cli star [--browser]` | Star the public repository on GitHub (only when you ask) |
+| `vidbyte-cli agents suggest run --goal "..." [--count 5]` | Generate and independently critique ranked next-action ideas with handoffs |
+| `vidbyte-cli agents suggest categories [--view-all|--view ID]` | Inspect the 31 suggestion categories (no model, no credentials) |
+| `vidbyte-cli agents suggest handoff --input result.json --idea idea-003` | Extract one handoff packet (no model) |
+| `vidbyte-cli agents suggest project create --key KEY --title TITLE --description TEXT` | Create a local suggestion-memory project (no model) |
+| `vidbyte-cli agents suggest project list` | List local suggestion-memory projects (no model) |
+| `vidbyte-cli agents suggest feedback accept\|reject --project KEY --suggestion TEXT [--reason TEXT]` | Record explicit user feedback for a project (no model) |
+| `vidbyte-cli agents bug-finder run --github-repo OWNER/NAME --project-type web\|cli\|sdk [--app-url URL] [--max-bugs N] [--linear]` | Hunt a GitHub repository for bugs, one fresh Codex agent per bug, with one artifact per bug and, with `--linear`, one Linear issue per bug |
+| `vidbyte-cli agents bug-finder mark --github-repo OWNER/NAME --bug ID --state STATE` | Set one bug's state in a repository's bug ledger (no model) |
+| `vidbyte-cli agents bug-finder sync --github-repo OWNER/NAME [--linear-workspace WS] [--linear-team KEY]` | File a ledger's open bugs as Linear issues, never the same bug twice (no model) |
+| `vidbyte-cli agents infinite-memory run [TASK] [--prompt-file FILE] [--workspace DIR] [--seed FILE] [--no-sync] [--max-cost-usd USD]` | Run the InfiniteMemoryAgent on a task here and print its handoff. Model calls bill your Vidbyte key at the model's rate + 2% (an exported `OPENAI_API_KEY` is relayed on OpenAI models). Unless `--no-sync`, the task, events, handoff and notes stay in your account 90 days; raw model turns never leave. Its shell runs as you: it can read your files, keyring and unlisted secrets, and sees `OPENAI_API_KEY` but no Vidbyte or other provider key. `--max-cost-usd` (default 5) counts priced calls before the fee; running pairs can pass it. About one busy synced run per key fits the sync rate limit |
+| `vidbyte-cli agents infinite-memory resume --run-id RUN_ID [--workspace DIR] [--no-sync] [--max-cost-usd USD]` | Continue a stopped infinite-memory run (model calls billed like `run`: rate + 2%), or only finish uploading a finished one (no model call) |
+| `vidbyte-cli github link` | Link a GitHub account through GitHub's device flow; the token stays in the system keyring |
+| `vidbyte-cli resolve setup --repo OWNER/NAME --harness opencode\|grok\|muse [--harness-model M] [--every MINUTES] [--check CMD] [--skill PATH]` | Propose a scheduled merge-conflict resolver workflow, its two sealed secrets, and its label in each repository of one owner |
+| `vidbyte-cli resolve run --repo OWNER/NAME --harness opencode\|grok\|muse [--max-prs N] [--recent] [--parallel-number N]` | Resolve one repository's conflicting pull requests once with a coding agent, as the scheduled workflow does |
+| `vidbyte-cli browserbase login [--with-token]` | Check and store the Browserbase API key web bug hunts use for their cloud browser |
+| `vidbyte-cli linear login [--with-token]` | Check a Linear personal API key and store it for the workspace it belongs to |
+| `vidbyte-cli linear logout [--workspace WS]` | Remove one connected Linear workspace's key and record |
+| `vidbyte-cli linear workspaces` | List the connected Linear workspaces and the default (offline) |
+| `vidbyte-cli linear use WORKSPACE [--team KEY]` | Choose the default Linear workspace and, optionally, its default team |
+| `vidbyte-cli linear teams [--workspace WS]` | List a connected Linear workspace's teams, live from Linear |
+| `vidbyte-cli slack add NAME` | Save a Slack incoming-webhook URL, read from stdin or a hidden prompt, under NAME for `--send-to slack:NAME` |
+| `vidbyte-cli slack list` | List the saved Slack webhook names, never the URLs (offline) |
+| `vidbyte-cli slack remove NAME` | Forget one saved Slack webhook; an unknown NAME changes nothing |
+| `vidbyte-cli resend login [--with-token]` | Check and store a Resend API key, reporting full or sending-only access |
+| `vidbyte-cli agentmail login [--with-token]` | Check and store an AgentMail API key |
+| `vidbyte-cli mailgun login [--with-token]` | Check and store a Mailgun account API key |
+| `vidbyte-cli mailchimp login [--with-token]` | Check and store a Mailchimp Marketing API key |
+| `vidbyte-cli brevo login [--with-token]` | Check and store a Brevo API key |
+| `vidbyte-cli klaviyo login [--with-token]` | Check and store a Klaviyo private API key |
+| `vidbyte-cli sendgrid login [--with-token]` | Check and store a SendGrid API key |
+| `vidbyte-cli ses login --access-key-id ID --region REGION [--with-token]` | Check and store an Amazon SES IAM access key for one region |
+| `vidbyte-cli gmail login` | Sign in to Gmail in the browser and store a send-only grant |
+| `vidbyte-cli outlook login` | Sign in to Outlook in the browser and store a send-only grant |
+
+The Resend and email provider logins check a credential with the provider and keep it in the
+system keyring only; nothing reads it back yet. The six key logins and `ses login` read the
+secret from a hidden prompt or, with `--with-token`, from stdin. `gmail login` and
+`outlook login` ask only for permission to send email, through an OAuth app you register
+yourself: set `VIDBYTE_GMAIL_CLIENT_ID`, plus `VIDBYTE_GMAIL_CLIENT_SECRET`, which Google
+requires for Desktop app clients, or `VIDBYTE_OUTLOOK_CLIENT_ID`. The consent link opens in
+your browser and is also printed on stderr; the login waits up to 5 minutes for approval.
+
+### Universal agent options
+
+Every agent command (`agents suggest run`, `agents bug-finder run`, `agents infinite-memory run` and
+`resume`, `runtime same-host-ensemble`, `runtime persistence`, `runtime task-board run`, and
+`runtime stages run`) accepts the options below, with the same spelling and validation. `--model`,
+`--reasoning-effort`, and `--instructions` are checked, and the instruction files are read, before
+any credential lookup, paid admission, or model call; an invalid value exits with status 2 as
+`INVALID_ARGUMENT`, and nothing is charged. `--send-to` targets and their credentials are checked
+next, still before any admission or model call. The values are never sent to Vidbyte, except that a
+synced `agents infinite-memory` run stores its `--model`. The runs ledger keeps `--model` and
+`--reasoning-effort` in each run's record, but never the `--instructions` file paths or the
+`--send-to` targets, and no task-board checkpoint keeps any of them, so a task-board resume needs
+them passed again.
+
+| Option | Default | Meaning and reach |
+|--------|---------|-------------------|
+| `--model MODEL` | installed Codex default (suggestion: `gpt-6-sol`) | The model id the agents run on. Suggestion: the generator only, while `--critic-model` keeps choosing the critic. Ensemble: every turn and fork. Persistence: the agent. Task board: every task agent. Stages: every stage whose `--stage-model` is omitted or empty. Bug finder: every hunt agent. Infinite memory: every agent of the tree, on the model's own provider. |
+| `--reasoning-effort` | provider default (suggestion: `high`; stages: `medium`) | `none`, `minimal`, `low`, `medium`, `high`, or `xhigh` for every agent the command starts; an empty value means unset. In stages it applies only when `--stage-effort` is omitted. Infinite memory refuses it. |
+| `--instructions FILE` | none | Repeatable. Each Markdown or text file is appended, after a blank line, to the system prompt of every agent the command starts, ensemble forks and suggestion critics included. An ensemble fork also gets the text at the end of its first turn. At most 8 non-empty UTF-8 files and 20,000 bytes in total; errors name the file's position, never its path or contents. |
+| `--send-to TARGET` | none | Repeatable. `slack` posts to the webhook in `SLACK_WEBHOOK_URL`; `slack:NAME` to the one saved with `slack add NAME`; `github:OWNER/NAME` opens an issue with `GITHUB_TOKEN`, else the `github link` account; `linear` or `linear:TEAM` opens an issue with the `linear login` key, in the default team unless TEAM is given. The result is sent after a normal finish, with one receipt line per target on stderr and stdout unchanged. A failed send exits 1 after every target was tried, with the result still on stdout. A dry run or prompt preview sends nothing. Needs a vidbyte-sdk release with the output connectors. |
+
+Instruction files carry developer-instruction authority over every agent the command starts,
+including agents that can edit your workspace, so pass only files you wrote or reviewed. Their
+text is repeated in every agent's prompt, which multiplies its token cost on large runs.
+
+### Turn a goal into ranked, critiqued next actions (Suggestion Agent)
+
+The [Suggestion Agent](https://vidbyte.pro/agents/suggestion-agent) drafts next actions for one
+goal, has an independent critic review them, and returns the survivors ranked, each with a handoff.
+
+`agents suggest run` takes one nonempty `--goal` plus optional repeated context and `--files`
+values. It takes no JSON input file. Both roles default to `gpt-6-sol` on the `openai` provider at
+`high` reasoning effort: `--model` sets the generator's model, including its extra-compute
+generators, `--critic-model` independently sets the reviewer's, and `--reasoning-effort` replaces
+the effort for every role. `--count` accepts 2–100, `--rounds` accepts 1–8, `--max-output-tokens`
+caps each reply at up to 128,000 tokens (default 32,000), and `--extra-compute` runs one focused
+generator context per selected category before critique. `--dry-run`, `categories`, `handoff`,
+`project`, and `feedback` never call a model, so they need no key and are never charged.
+
+The suggestion agent is usage-based: there is no per-suggestion price. Every generator and
+critic turn is one call to Vidbyte's model gateway (`POST /api/v1/models/generate`), billed to
+the balance of your stored Vidbyte key at that model's rate in the Vidbyte SDK pricebook plus
+2%. A default run makes about five calls: a first draft, then a critique and a revision per
+round. The key needs the `models:invoke` permission (`vidbyte-cli login` with a key created at
+<https://vidbyte.pro/settings/api>); no Codex install, OpenAI login, or OpenAI key is involved.
+The goal, its context, `--files` bodies, attachments, and loaded project memory are sent through
+Vidbyte to OpenAI on each call. The result's `usage` field reports the model calls and the
+input, output, and cached tokens the run used; the billed amounts appear at
+<https://vidbyte.pro/usage>. `--max-total-tokens` and `--timeout-seconds` are checked before
+each call, never mid-call, because a call in flight is billed when it completes. If the balance
+or the key's daily model-spend cap runs out after a slate exists, the run stops with
+`gateway_limit` and returns the latest reviewed slate; before that, it fails with the
+balance or rate-limit error.
+
+Context is limited to 5,000,000 characters per item and in aggregate, with truncation or omission
+recorded in the result manifest. Each surviving idea carries one primary category, evidence
+references, decisions, eight-to-ten considerations, completion checks, and a deterministic handoff
+whose authority is not granted by the handoff itself.
+
+Suggestion projects are optional local JSON memory. The catalog is stored in the platform-native
+Vidbyte data directory as `suggestions/projects.json`, and each project links to one file under
+`suggestions/projects/` holding its ordered accepted and rejected feedback. Create a project
+once, pass `--project KEY` to a run to load its title, description, and feedback as context,
+then record the user's explicit reactions with the feedback commands the run prints. Silence,
+ambiguity, and unrelated implementation are never acceptance or rejection. Without
+`--project`, a run reads no project file.
+
+```bash
+vidbyte-cli agents suggest project create \n  --key vidbyte-cli \n  --title "Vidbyte CLI" \n  --description "The local CLI and agent runtime."
+vidbyte-cli agents suggest run --project vidbyte-cli --goal "Choose the next CLI improvement."
+vidbyte-cli agents suggest feedback reject \n  --project vidbyte-cli \n  --suggestion "Use MongoDB for project memory" \n  --reason "It adds unnecessary backend infrastructure."
+```
+
+### Bug finder agent
+
+`agents bug-finder run --github-repo OWNER/NAME --project-type web|cli|sdk` hunts a GitHub
+repository for bugs in a fresh shallow clone that is deleted when the run ends. Each turn, one
+fresh Codex agent reports one new bug with full evidence or reports nothing new; the run stops
+there, at a bug already in the ledger, or after `--max-bugs` (1–50, default 5) bugs. A web hunt
+also needs `--app-url` and a Browserbase key stored with `browserbase login`. Each bug gets a
+JSON and a Markdown ticket under `bug-finder/projects/OWNER/NAME/` in the Vidbyte data
+directory, and `agents bug-finder mark` sets its ledger state offline.
+
+`github link` uses GitHub's device flow: approve the printed one-time code on github.com, and
+the token is kept in the system keyring only. Set `VIDBYTE_GITHUB_CLIENT_ID` to the client ID
+of a GitHub OAuth app or GitHub App with device flow enabled.
+
+`linear login` connects one Linear workspace per personal API key and keeps the key in the
+keyring. `linear workspaces`, `linear use WORKSPACE [--team KEY]`, `linear teams`, and
+`linear logout` list, choose, inspect, and forget connected workspaces. With `--linear`, or
+`--linear-workspace` or `--linear-team`, each new bug is filed as a Linear issue the moment it
+is recorded, with a priority from its severity, and a regression adds one comment. The issue
+id is saved in `linear.json` before Linear is asked, so a retry never files a bug twice, and
+`agents bug-finder sync` files every open bug that has no issue yet.
+
+The agent runs repository code in Codex's workspace-write sandbox on your own Codex login, with
+Vidbyte keys, `CODEX_API_KEY`, and non-OpenAI provider keys blanked. Code it runs can still
+read `OPENAI_API_KEY`, any other secret in your environment (such as `GITHUB_TOKEN` or `AWS_*`),
+and the plaintext fallback credential files in the Vidbyte data directory, so run it on a
+machine or account that does not hold them.
+
+### Merge-conflict resolver
+
+`resolve setup --repo OWNER/NAME --harness opencode|grok|muse` proposes a scheduled GitHub
+Actions workflow in each repository, through a setup pull request you merge yourself, and seals
+`VIDBYTE_RESOLVE_GITHUB_TOKEN` and `VIDBYTE_RESOLVE_API_KEY` into its Actions secrets. Every
+`--every` minutes (default 15) the workflow runs `resolve run`, which merges each conflicting
+pull request's base branch into its branch, asks the coding agent to resolve the conflicted
+files, runs `--check`, and pushes the merge commit. A pull request it cannot resolve gets one
+comment and the `needs-human-resolve` label; remove the label or push a commit to retry it.
+`resolve run` needs git 2.38 or newer, for `git merge-tree --write-tree`; with an older git it
+fails every pull request it would examine, writes nothing to any of them, and exits 1, while a
+run with nothing to examine still exits 0.
+
+The fine-grained token needs Contents, Pull requests, Workflows, and Secrets read and write on
+only the repositories you name, and one setup covers one owner. Code that runs in this
+repository's Actions with this token can push to every repository it covers, add a workflow that
+prints every Actions secret of those repositories, and overwrite those secrets. One token per
+repository contains that to one repository. Every scheduled run bills Actions minutes even with
+nothing to do: at every 15 minutes that is about 2,880 job starts a month, each at least one
+billed minute in a private repository. Model usage bills your own key, and GitHub pauses
+schedules in a public repository after 60 days without activity.
+
+### Persistent deep research from the terminal, alongside Claude Code or Codex (Research harness)
+
+Start a run from your terminal, or let Claude Code or Codex start it with `--json`; it keeps going
+after the terminal closes.
+
+`research` commands start and follow runs of the
+[Vidbyte Research harness](https://vidbyte.pro/docs/harnesses/research), whose agent is the
+Persistent Researcher. Research runs on Vidbyte's servers. It is not a local skill, and the
+`/research` learning skill is unrelated. This CLI admits runs, reads their durable status, and
+lists the threads you own; deep dives, artifact bodies, sources, and exports remain
+website-only.
+
+A thread is addressed only by the public ID that `research start` and `research threads`
+print. That is the value to pass back to `research add` and `research thread`; the internal
+identifier some other tools show is rejected before a request is sent.
+
+`research status` and `research watch` report state, phase, continuation count, and a
+timestamp — the whole of what the API publishes for a run. Neither prints a thread ID,
+because the status route does not carry a usable one.
+
+Starting, adding, and resuming are priced and idempotent. Each sends a generated
+`Idempotency-Key` and reports it, so `--idempotency-key <that value>` retries a mutation
+whose outcome you did not see without paying for it twice. `research watch` polls every ten
+seconds and backs off from there: API keys are metered on a weighted per-minute budget, and
+polling harder can exhaust the budget you need to start the next run.
+
+### Local runtime primitives
+
+`runtime` commands execute on your machine, driving a native coding agent you already
+installed. Vidbyte charges a small flat admission fee for the orchestration; the model usage
+runs against your own provider subscription, not ours.
+
+The base install already includes the Codex integration these commands use, so there is no
+extra package to install.
+
+### Run several Codex agents in parallel and implement the best approach (Ensemble Agent)
+
+`runtime same-host-ensemble <task>` runs four stages on one machine. A planner agent reads your task
+and generates the ensemble's roles, writing each role's complete system prompt. Each role then runs
+concurrently in its own read-only fork and returns 5 to 10 distinct approaches, each with its pros,
+cons, risks, and the files it would touch. A role cannot edit anything — the sandbox forbids it, not
+just the prompt. A selector fork then narrows every approach from every role down to one, in rounds:
+each round keeps a fifth of what it was given, weighs the pros and cons of every candidate it keeps,
+and records why the rest were dropped. Finally one write-enabled fork receives the selected approach
+and the selector's brief, and does the work. That last fork is the only agent in the topology
+permitted to modify your workspace.
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `--host` | `codex` | The only accepted value: Codex is the one host with verified thread-fork and per-fork sandbox support. |
+| `--roles` | `3` | How many specialist roles the planner invents for this task (3-100). More roles widen the approach slate the selector narrows. |
+| `--model`, `--reasoning-effort`, `--instructions` | see [Universal agent options](#universal-agent-options) | Reach every turn and fork in the run. |
+| `--idempotency-key` | generated | Reuse a key to retry a priced admission without being charged twice. Omit to generate one per invocation. |
+
+A role that times out (after a fixed 300-second bound) or fails is reported in the result and the
+run continues. The run stops only when every role failed.
+
+Two costs are worth separating. Admission is two cents, charged once, after the CLI has
+confirmed your input, the SDK, and the host — so a missing Codex never costs you anything.
+The grant is then verified through the layered runtime gate before any agent starts; a
+rejected grant fails the run without starting a single fork. The larger cost is your own
+provider usage: the SDK opens a fresh Codex app-server per turn
+and per fork, so a three-role run is roughly a dozen of them against your subscription, and
+`--roles 100` is a thousand approaches for the selector to read. Raise it deliberately.
+
+### Keep a Codex session working past its first answer (Persistent Agent)
+
+The [Persistent Agent](https://vidbyte.pro/agents/persistent-agent) gives one Codex session your
+task, then a fixed number of further turns that ask it to check and improve its own work.
+
+```bash
+vidbyte-cli login
+vidbyte-cli provider login openai
+vidbyte-cli runtime persistence "Your exact task" --strength 1
+```
+
+Install Codex on PATH first. OpenAI credentials resolve from `OPENAI_API_KEY`, then the
+selected profile's keyring or approved file fallback. They are passed only to the Codex child;
+native Codex login is unchanged. The configured Codex model, or the one `--model` names, must be
+available to that OpenAI API key.
+
+Strength tiers 1–6 send **6, 8, 20, 40, 70, 100 additional turns**, after the exact original task.
+All turns resume the same explicit session ID. `--host auto` selects Codex; other hosts are
+unsupported. Codex runs with workspace-write sandboxing, without a sandbox bypass.
+
+Each invocation costs two cents from the Vidbyte API wallet, plus your OpenAI usage. Task text and
+provider credentials never enter Vidbyte admission requests.
+
+Use a caller-chosen `--idempotency-key` (8–128 allowed characters) to recover an uncertain
+admission request without another debit. Reusing it does not resume local work: a new CLI
+invocation starts a new Codex session, so do not rerun a completed task with a recovery key.
+Ctrl+C cancels the active SDK turn and closes its Codex connection.
+A failed or hour-long turn stops the loop;
+completed local work remains, and the flat admission fee is not automatically refunded.
+This is a foreground loop, not a daemon that survives terminal closure.
+
+Only the final response is written to stdout; progress goes to stderr. JSON output includes
+`session_id`, `continuation_turns`, and `text` in the standard result envelope.
+
+### Runs ledger
+
+```bash
+vidbyte-cli runs list
+vidbyte-cli --json runs last
+```
+
+Eight agent commands record every run they start on this machine: `agents suggest run`,
+`agents bug-finder run`, `agents infinite-memory run`, `agents infinite-memory resume`,
+`runtime persistence`, `runtime same-host-ensemble`, `runtime task-board run` and
+`runtime stages run`. Research runs are not recorded; their status lives on the backend.
+
+A recorded run prints its id. With `--json`, the result
+document, or the error envelope on stderr, carries it as the top-level `run_id`. With
+`--format jsonl`, the first record is a `runs.started` document naming the run, and every
+record after it carries the same `run_id`. Human output prints `Run ID: <id>` on stderr when
+the run starts, and a human error repeats it, so stdout keeps only the result. If the ledger
+cannot record the run, the run still works, prints one warning, and carries no id.
+
+Each run is one JSON file. It holds the request (the command, the working directory and the
+parsed options), the one result document the run printed or the error envelope it failed
+with, and the run's status, process id, start time and finish time. Nothing else is saved:
+no progress messages, no admission details, never the value of an idempotency key, and never
+the `--instructions` file paths.
+
+Records live in the `runs` directory of the CLI's per-user state directory:
+`%LOCALAPPDATA%\Vidbyte\vidbyte-cli\runs` on Windows, `~/.local/state/vidbyte-cli/runs` on
+Linux and `~/Library/Application Support/vidbyte-cli/runs` on macOS, or under
+`$XDG_STATE_HOME/vidbyte-cli` when that variable is set. `vidbyte-cli --json runs list` prints
+the exact path as `runs_dir`. Task text is saved as you typed it, so treat the directory like
+your shell history.
+
+`vidbyte-cli runs list` shows the runs still going:
+`running` means the process is alive, and `abandoned` means the run's outcome was never
+recorded, because its process died or it could not save its final state, so its work may
+still have finished. `vidbyte-cli runs list --all` adds finished runs (`succeeded`, `failed`,
+`interrupted`), newest first. `vidbyte-cli runs show` takes a run id or a unique prefix of it.
+
+The read verbs are offline and free and need no API key. Write `--json` before `runs`,
+because it is a root option. There is no retention: records accumulate until you delete them.
+To remove a run, delete its `.json` file and any `.lock` file of the same name from the runs
+directory while no recorded run is live.
+
+## Use Vidbyte agents from Claude Code or Codex
+
+`vidbyte-cli mcp serve` is a local [Model Context Protocol](https://modelcontextprotocol.io)
+server. Your coding agent describes what you need; Jev, TypeSafe's decision model, which Vidbyte
+runs (the model behind [JevAgent](https://vidbyte.pro/docs/jev-agent)), picks the Vidbyte agent
+that fits on Vidbyte's backend; and the agent runs from this CLI on your own machine. The coding
+agent never writes or runs a `vidbyte-cli` command itself: every command the server starts comes from a fixed allowlist, with your request as its task text.
+
+<!-- mcp-name: pro.vidbyte/vidbyte-cli -->
+
+Register it with one command (needs [`uv`](https://docs.astral.sh/uv/); works the same on
+Windows, macOS, and Linux):
+
+```bash
+claude mcp add --scope user vidbyte -- uvx --from "vidbyte-cli[mcp]>=0.3.0" vidbyte-cli mcp serve
+codex mcp add vidbyte -- uvx --from "vidbyte-cli[mcp]>=0.3.0" vidbyte-cli mcp serve
+```
+
+Without `uv`, register `pipx run --spec "vidbyte-cli[mcp]>=0.3.0" vidbyte-cli mcp serve` instead.
+The `>=0.3.0` bound matters: `uvx` and `pipx run` reuse a cached environment that satisfies the
+requirement, and releases before 0.3.0 have no `mcp serve`.
+Codex gives a server ten seconds to start by default, and the first `uvx` launch downloads the
+package, so set `startup_timeout_sec = 60` under `[mcp_servers.vidbyte]` in
+`~/.codex/config.toml`. Pass `--workspace <project root>` after `serve` when your client does not
+start servers in the project directory; Claude Code's `CLAUDE_PROJECT_DIR` is used otherwise.
+
+**Never put an API key in the registration command** (for example `-e VIDBYTE_API_KEY=...`):
+clients store that command in plain text. When a key is missing, the server opens a page on
+`127.0.0.1` in your browser where you paste it; the key is verified, stored in your
+operating-system keyring, and never passes through the chat. If your client cannot open that
+page, the tool tells you to run `vidbyte-cli login` (and `vidbyte-cli provider login openai` for
+the persistence or task-board agent) in a terminal. If Codex stops waiting while the page is open, finish the
+page and call the tool again; the stored key is used from then on. Any Vidbyte account, the free
+plan included, can create an API key at <https://vidbyte.pro/settings/api>.
+
+| Tool | What it does | Cost |
+| --- | --- | --- |
+| `vidbyte_setup_status` | Reports which keys and hosts are missing | Free, offline |
+| `vidbyte_plan(request)` | Asks Jev one yes/no question per agent and stores a 30-minute plan | One metered Jev call billed to your Vidbyte balance |
+| `vidbyte_run(plan_id, request_id)` | Runs the plan's recommended (or another passing) agent; your client asks you first | The agent's own price: ensemble, persistence, and task board charge a two-cent admission plus OpenAI usage; suggestion bills each model call to your Vidbyte balance at its model's rate plus 2%; research is usage-based up to $5.00 |
+| `vidbyte_run_status(job_id)` | Reports a job's status and pages its result | Free, offline |
+| `vidbyte_cancel_run(job_id)` | Stops a running job | Free; an admission or completed model calls are not refunded |
+
+The routed agents are the suggestion agent, the same-host ensemble, the persistence agent,
+research, and the task board. The ensemble, persistence, and task-board agents edit files in the
+workspace, and only one file-writing agent runs in a workspace at a time. The task board can
+divide one broad request into up to five independent tasks and runs them sequentially; each task
+agent uses the same workspace and your stored OpenAI key. Task-board jobs can run for up to 30
+days and can be stopped with `vidbyte_cancel_run`. A research job completes when Vidbyte
+accepts the run; follow it with `vidbyte-cli research watch <run_id>`. A job whose server stopped reads as `interrupted`
+and is never restarted automatically. Local state lives in the CLI's state directory under
+`mcp/`; remove the server with `claude mcp remove vidbyte` or `codex mcp remove vidbyte`.
+
+## Configuration
+
+| Variable | Meaning |
+| --- | --- |
+| `VIDBYTE_API_URL` | API host (default `https://vidbyte-backend.onrender.com`) |
+| `VIDBYTE_API_KEY` | API key; overrides the stored credential for the current shell |
+| `VIDBYTE_PROFILE` | Profile name; the lower-precedence equivalent of `--profile` |
+| `VIDBYTE_OUTPUT_FORMAT` / `VIDBYTE_COLOR` | Presentation defaults |
+| `VIDBYTE_REQUEST_TIMEOUT_SECONDS` | Per-request timeout |
+
+Non-secret settings resolve command option → environment → selected profile → default
+profile → built-in, and `vidbyte-cli config get <key>` reports both the effective value and
+which layer supplied it. `config set` accepts `api_url`, `output_format`, `color`, and
+`request_timeout_seconds`.
+
+API keys resolve separately: environment → OS keyring → permission-restricted file. An
+environment key is never persisted, and the restricted file is used only with explicit
+consent. Configuration, cache, state, and data live in the platform's standard application
+directories; `~/.vidbyte/` is still read, and is copied across by a verified migration that
+leaves the originals in place.
+
+## Architecture
+
+> **Status:** persistence requires a backend deployment with persistence activation and
+> grant verification. Adversarial-team is planned (no executor yet).
+
+Local runtimes are separate from hosted harnesses. Vidbyte authenticates a launch and
+charges a flat admission fee from the API-key wallet, while persistence executes in Codex
+using the caller's OpenAI API key. x402 funds that wallet through the backend's
+`POST /agent/topup` route; machine environment and repository contents are never uploaded
+for admission.
+
+Every command is static and known at release time. Runtime discovery adds one authenticated
+catalog route. Persistence calls activation and authenticated grant verification before
+launching Codex.
+
+The application composition root lives in `src/vidbyte_cli/lib/runtime`. It constructs one
+invocation context, binds stdin/stdout/stderr through `lib/io`, resolves output and error
+policy, and builds the Click tree.
+
+## Verify
+
+```bash
+python -m pip install -e ".[dev]"
+python scripts/run_ci.py
+```
+
+The canonical gate runs Ruff lint/format checks, strict mypy, byte compilation, offline
+command smoke checks, sdist/wheel build, Twine metadata validation, and an installed-wheel
+smoke check. GitHub Actions invokes the same script on Linux, Windows, and macOS.
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, and both versions in `server.json` (the MCP Registry
+entry), in one pull request. PyPI versions are permanent, so the bump is the release
+decision. While GitHub Actions cannot run here, release from a clean `main` with
+`python scripts/release_local.py` (`gh` signed in, a vidbyte-cli PyPI token in
+`PYPI_API_TOKEN`; `--dry-run` publishes nothing). It runs the gate above, uploads exactly
+the files it verified, then tags `v{version}` and creates the GitHub Release on the public
+`cerredz/vidbyte-cli`. When Actions runs, `tag-release.yml` and `release.yml` do the same.
+
+## API balance
+
+```bash
+vidbyte-cli billing balance
+vidbyte-cli --json billing balance
+```
+
+`billing balance` shows what the configured key can spend. The read is free, never pays, and
+answers even on an empty wallet, so check it first when a call fails for lack of balance.
+`spendable_balance_cents` is what a new call can draw on: the available balance minus what
+runs in progress are holding. `vidbyte-cli billing top-up --confirm` adds the $5.00 minimum
+through x402, and only with the account owner's approval. Out of balance mid-run,
+`agents infinite-memory` exits 5 with its spend and resume command.
+
+## Runtime admission payments
+
+`vidbyte-cli runtime persistence "your task"` uses your authenticated Vidbyte API
+balance by default. The flat $0.02 admission is recorded as ordinary API usage.
+Local Codex model usage is still paid through your OpenAI credentials.
+
+To pay the admission directly with x402, set `VIDBYTE_X402_PRIVATE_KEY` in your
+shell and run `vidbyte-cli runtime persistence "your task" --with-x402-payment`.
+A Vidbyte API key with `runtime:write` is required for ownership in both modes.
+`VIDBYTE_X402_NETWORK` defaults to Base (`eip155:8453`); Base Sepolia
+(`eip155:84532`) is supported for testing. Keep private keys out of command arguments.
+The wallet must already hold the network's USDC; the CLI does not fund it.
+
+Both modes verify the signed receipt against Vidbyte's database before launching
+Codex. The API-balance path also verifies the exact usage-ledger debit. Payment
+credentials are not passed to Codex. The CLI never switches payment methods automatically.
+Recover a failed admission with the same `--idempotency-key`; a retry preserves the
+original grant and expiry. An uncertain payment outcome must be reconciled before
+starting another purchase. Verification does not refund a failed local execution.