boltz-check-status
Boltz job status and result recovery. Use when listing jobs, checking progress, resuming downloads, recovering results, or downloading an existing job ID. Not for starting new jobs.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- boltz-check-status
- description
- Boltz job status and result recovery. Use when listing jobs, checking progress, resuming downloads, recovering results, or downloading an existing job ID. Not for starting new jobs.
02 资源文件 3
- 参考文档agents/openai.yaml229 B
- 参考文档references/api.md10.6 KB
- 参考文档references/resume.md2.1 KB
03 SKILL.md 正文
Workflow
If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying.
If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first.
If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.
Use this skill to recover state across sessions and to inspect or download results for prior Boltz jobs. No payload authoring — this skill only calls list / retrieve / download-results / download-status.
Use four modes:
- Local progress: if the user knows the run name / run dir, prefer
download-statusbefore remote API calls. - List recent jobs: enumerate all six resources, merge, and sort by
created_atdescending. - Retrieve one job: use the job ID prefix when known; otherwise probe resources until one succeeds.
- Resume/download results: run
download-resultswith the original run name when possible. Never runstartagain to resume.
ADME jobs use the prefix adme_pred_* and show up in Modes 1-2 (list / retrieve) like the others. ADME has no download-results/archive step, so Modes 3-4 don't apply — recover its scores by re-running retrieve (read output.molecules[]) or from the local run.json.
Read references/resume.md before recovering a dropped session, mapping job ID prefixes, or choosing a run name for download-results. Read references/api.md for per-resource list columns, retrieve fields, and result semantics.
Command Pattern
# Replace placeholders with concrete absolute paths before running.
# Local helper: inspect local checkpoint state without API calls.
boltz-api --format json download-status \
--name "<run-name>" \
--root-dir "/absolute/path/boltz-experiments"
# Mode 1: list recent jobs across all 6 resources.
# Note: the CLI emits one JSON object per record (streamed, no {data:[]} wrapper).
# --limit is per-page and the CLI auto-paginates, so cap each explicit command with head.
boltz-api predictions:structure-and-binding list --limit 20 --format jsonl | head -20
boltz-api predictions:adme list --limit 20 --format jsonl | head -20
boltz-api small-molecule:library-screen list --limit 20 --format jsonl | head -20
boltz-api small-molecule:design list --limit 20 --format jsonl | head -20
boltz-api protein:library-screen list --limit 20 --format jsonl | head -20
boltz-api protein:design list --limit 20 --format jsonl | head -20
# Mode 2: retrieve by ID. Pick the resource from the ID prefix in the workflow
# notes above. If the prefix is unknown, run these one at a time until one succeeds.
boltz-api predictions:structure-and-binding retrieve --id "<job-id>" --format json
boltz-api predictions:adme retrieve --id "<job-id>" --format json
boltz-api small-molecule:library-screen retrieve --id "<job-id>" --format json
boltz-api small-molecule:design retrieve --id "<job-id>" --format json
boltz-api protein:library-screen retrieve --id "<job-id>" --format json
boltz-api protein:design retrieve --id "<job-id>" --format json
# Mode 3: resume download. Use the agent runtime's managed long-running command mode.
boltz-api download-results \
--id "<job-id>" --name "<run-name>" \
--root-dir "/absolute/path/boltz-experiments" \
--poll-interval-seconds 30
Always Do This
- If the user has a run name / slug or run dir and only wants local downloader state, prefer
download-statusbeforeretrieve. - Use an absolute output root and keep passing it through
--root-dir. Do notcdinto the run directory; that makes later relative paths point at the run directory instead of the user's workspace. - On an unfamiliar job ID, run Mode 2 (retrieve) before Mode 3 (download) so you capture
idempotency_key. - Prefer the original run-name slug over the job ID as
--name— it resumes into the existing dir with cursor. - In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with
boltz-api. Prefer running the sixlist/retrievecommands explicitly over generating them from a shell loop; a fixed| head -20cap is okay when listing to avoid runaway streamed output. - Prefer the agent runtime's background/non-blocking command mode for
download-results. In Codex specifically, keepdownload-resultsin the foreground and set the shell tool yield to 1000 ms; Codex will return asession_idif the command is still running. Do not append&or usenohupin Codex because the tool runner may clean up shell-backgrounded descendants before.boltz-run.jsonis fully written. - After the background/session starts, do not manually wait on it or run ad hoc polling loops. In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat that checks
download-statusperiodically, posts only material status changes or terminal completion/failure, and stops once terminal. If the current host has no heartbeat automation support, do not claim an automatic next check; report the job ID, run name, output directory, and the command needed to checkdownload-status. download-resultsnow emits machine-readable JSONL progress on stderr by default. Add--progress-format text --verboseonly when you explicitly want human-readable logs.- Prefer
download-statusfor local checkpoint state. In Codex hosts with heartbeat automation support, use it for automatic follow-up and poll the saved session with an emptywrite_stdinonly for interactive, user-requested progress checks. Don't loopretrieveunless the user wants fresh remote status. - If
retrievesurfaces only{"code":"VALIDATION_ERROR","message":"Request validation failed"}with nodetails, that's expected forpredictions:structure-and-bindingfailures — other endpoints include field paths. - Never run
startagain on a failed or interrupted job. Fix the payload and submit with a newidempotency-key, or just resume withdownload-results.
Escape Hatch
- Python SDK reference (per-resource
list/retrievemethods): https://api.boltz.bio/docs/api/python - CLI flag names:
boltz-api <resource> list --help,boltz-api <resource> retrieve --help,boltz-api download-results --help,boltz-api download-status --help
Outputs
- Local helper / Mode 1 / Mode 2 print structured data to stdout; present as a table.
- Mode 3 writes recovered artifacts under
<output-root>/<run-name>/— same layout as a fresh run. Read references/resume.md for resume behavior.
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.