boltz

Boltz Skills

Agent tooling for running Boltz workflows (structure prediction, molecular screening, de novo design) from AI coding assistants. Distributed as CLI-backed Claude Code, Codex, and Gemini CLI skill surfaces plus a Claude Desktop MCPB surface.

Surfaces

Surface	Consumer	Execution layer	Status
surfaces/claude-code-cli/	Claude Code	Skills shell out to boltz-api CLI	Active
surfaces/codex-cli/	Codex	Skills shell out to boltz-api CLI	Ships today
surfaces/gemini-cli/	Gemini CLI	Skills shell out to boltz-api CLI	Local surface
surfaces/mcpb/	Claude Desktop	Local MCP server shells out to boltz-api CLI	Active

The MCPB surface complements the skill plugins: Claude Code, Codex, and Gemini CLI get workflow skills, while Claude Desktop gets local MCP tools that run the same CLI flow.

Shared core

The CLI skill surfaces pull from core/:

Directory	Purpose	Consumed by
core/skills/cli/	CLI-variant skill bodies (shell commands)	claude-code-cli, codex-cli, gemini-cli
core/references/	Payload schema docs	All surfaces

Skill bodies and schema docs are symlinked into each surface, so editing in core/ propagates everywhere. Confirmed working under Claude Code plugin caching.

Quick start (local development)

# Run Claude Code with the development surface
claude --plugin-dir ./surfaces/claude-code-cli

Claude Code local install

The repo root is also a Claude Code marketplace named boltz-marketplace. It publishes one installable plugin named boltz, backed by a self-contained copy of the CLI-direct Claude Code skills under plugins/boltz.

For a local checkout:

claude plugin marketplace add "$PWD"
claude plugin install boltz@boltz-marketplace --scope user

Or use the install script:

scripts/install-claude-code-plugin.sh

To install from a local checkout instead of GitHub, run:

BOLTZ_CLAUDE_MARKETPLACE="$PWD" scripts/install-claude-code-plugin.sh

Restart Claude Code after installing. The installed boltz plugin requires boltz-api on PATH and either device-code auth via boltz-api auth login --device-code or BOLTZ_API_KEY.

When editing the shared skill source under core/ or Claude-specific files under surfaces/claude-code-cli/, refresh generated distribution surfaces:

scripts/generate-surfaces.sh

Treat plugins/boltz as generated output. Make source changes under core/ or surfaces/claude-code-cli/, then sync. CI verifies the generated copy, and a branch push workflow auto-commits regenerated plugin-copy changes when a development branch drifts.

Codex official plugin submission

The official Codex plugin copy is generated under plugins/boltz-compute-cli/. Its directory name matches .codex-plugin/plugin.json and its symlinked skill sources are dereferenced, matching the layout used by openai/plugins entries such as Netlify and Cloudflare.

For a zip artifact:

./scripts/package-plugins.sh         # writes dist/boltz-compute-cli-<version>.zip

For an openai/plugins PR, copy plugins/boltz-compute-cli/ into that repo's plugins/ directory and add the marketplace entry:

{
  "name": "boltz-compute-cli",
  "source": {
    "source": "local",
    "path": "./plugins/boltz-compute-cli"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Science"
}

For the full development lifecycle, see CONTRIBUTING.md.

Gemini CLI extension

The Gemini CLI extension source lives under surfaces/gemini-cli/. It bundles the same shared CLI-backed skills with a gemini-extension.json manifest and a concise GEMINI.md context file for Gemini-specific shell behavior.

For local development:

gemini extensions link ./surfaces/gemini-cli

Restart Gemini CLI after linking, then verify with /extensions list and /skills list.

For public distribution, mirror surfaces/gemini-cli/ into a dedicated public install repo with symlinks dereferenced. In that repo, gemini-extension.json must live at the repo root.

To open a sync PR against the public release repo:

RELEASE_REPO=boltz-bio/boltz-gemini-cli scripts/release-gemini-repo.sh

Release builds

./scripts/package-plugins.sh         # Writes Claude/Codex/Gemini zips and boltz-mcpb-<version>.mcpb into dist/

CI (.github/workflows/release.yml) runs these on every tagged release and attaches artifacts to the GitHub Release.

Claude Desktop MCPB