Working with agents

OpenBBQ is built to be driven, not just run. You can work every command by hand, or hand the tongs to an AI agent like Claude Code or Codex and let it cook. This page is the contract between the driver and the CLI: how output stays machine-readable, how to install the packaged skill that teaches an agent the whole workflow, and the rules agents are expected to follow.

Default: follow the Agent facade

For a one-prompt draft, initialize once and let agent next decide every step:

openbbq --json agent init '<source>' --workspace workspaces/demo --to zh
openbbq --json agent next --workspace workspaces/demo

Run the returned argv exactly for run_command; submit the complete response with agent apply for review_source or translate; run the returned finish command for finish; deliver the reported artifacts for done. Call agent next again after every successful action.

Do not guess the next command or create a second translation batch. The active lease pins the selected ids and content hashes, so repeating next is safe and an incomplete or stale apply is rejected. Translation actions also carry the generation rules, glossary context, and any local reference evidence the Agent needs. The full protocol is explained in Workflow model.

Machine-readable output

JSON is a structured text format that programs read easily. Pass the root --json flag — before the command name — and every command answers with one compact JSON object:

openbbq --json status --workspace workspaces/demo
openbbq --json export --workspace workspaces/demo --to zh --mode bilingual

When the output is not going to an interactive terminal (a TTY — the window where you type commands), as with Codex or CI, OpenBBQ emits that compact JSON automatically. Agents should still pass --json explicitly, to declare the contract instead of relying on detection.

Human progress and long-task hints go to stderr — a separate side channel for messages — or to the workspace manifest, so the machine-readable stream always stays parseable.

Exit and error behavior

• Success emits a result object and exits 0.
• A domain failure — the command understood you, but the work failed — emits a structured error with an error code, context, and often a fix. Follow the fix; do not parse the human prose or invent recovery commands.
• CLI usage errors (wrong flags, missing arguments) use the usage code.
• Unexpected failures use the internal code.

Poll long work

fetch, transcribe, and burn can take minutes. They write stage progress into the workspace manifest.json, so a second process can watch without interrupting:

openbbq --json status --workspace workspaces/demo

If a running stage shows no heartbeat for 60 seconds or more, status marks it stale — treat that as "go look", not "it finished".

Teach the agent the whole workflow

OpenBBQ ships a packaged skill — a ready-made instruction file an agent reads to learn the entire subtitle workflow. Install it with one command:

openbbq skill install

The default target is the shared agents directory, ~/.agents/skills/. Pick a different home per agent:

Use --target PATH for a custom parent directory, and --force to overwrite an installed copy.

Two skills are packaged:

• openbbq-subtitles (the default) — the full workflow, from raw video to cooked subtitles.
• bilibili-cover-safe-area — turn a video thumbnail into a cover that fits Bilibili's upload layout.

Select one with --name:

openbbq skill install --name bilibili-cover-safe-area

To read a skill without installing anything, print it:

openbbq skill show
openbbq skill show --language zh-CN
openbbq skill show --name bilibili-cover-safe-area --language en

Bounded context

Long videos mean hundreds of subtitle lines — too much for an agent to hold in its head at once. The review-style commands serve their items in small pages (offset/limit), so the agent works one focused batch at a time:

• openbbq asr batch — doubtful listening, a few items at a time; see Transcription and listening checks
• openbbq translate batch — lines waiting for translation; see Translation and review
• openbbq glossary audit — terminology review; see Glossaries

House rules for agents

• Ask before installing system dependencies, downloading large models, or writing browser login state.
• Keep OPENBBQ_HOME and workspace paths writable.
• Keep translation batches bounded, and run openbbq translate check between manual batches.
• Never use translate init --force unless discarding existing work is intentional.
• Preview exported subtitles before publishing or burning.

Where next?

• Workspaces and stages — what the agent is actually operating on.
• Quality gates — where OpenBBQ stops and waits for a decision.
• CLI reference — every command and option.