blatant-why

---

---

Quick Start (5 minutes)

You don't need to be a developer. If you can open a terminal and paste commands, you can run BY.

1. Install prerequisites

Tool	Install	Check
Node.js 18+	nodejs.org	node --version
Python 3.11+	python.org	python3 --version
uv	curl -LsSf https://astral.sh/uv/install.sh | sh	uv --version
Claude Code	npm install -g @anthropic-ai/claude-code	claude --version

2. Create your project

mkdir my-campaign && cd my-campaign
npx blatant-why init

This scaffolds everything: 11 MCP servers, 21 agents, 19 skills, 13 slash commands, and a CLAUDE.md orchestration file. Takes about 30 seconds.

3. (Optional) Configure compute

BY defaults to local GPU if one is available. Otherwise the first-run questionnaire will help you pick between local, HPC (RunPod / Modal / SLURM), or Tamarind cloud. See Compute Options below.

cp .env.example .env
# Add keys for whichever compute provider you'll use

4. Start designing

claude

Then just tell it what you want:

> "Design VHH nanobodies against PD-L1"

Or use the guided workflow:

> /by:plan-campaign

Or if it's your first time:

> /by:welcome

That's it. Claude Code handles the rest -- research, design, screening, and ranking.

---

What It Does

Give it a target protein. It researches across PDB, UniProt, and SAbDab. It plans a design campaign with statistical-strategy debate when the target is novel. It runs compute jobs on your local GPU (default), on your HPC (RunPod / Modal / SLURM via the by-deploy-compute skill), or on Tamarind Bio cloud. It screens every design for structural quality, sequence liabilities, and developability. It ranks candidates by composite score. When you submit them to the lab and the results come back, it ingests the CSVs, diagnoses which in-silico features predicted reality, and feeds the calibration back into the next round.

The whole pipeline runs inside Claude Code. No platform. No dashboard. No vendor lock-in.

---

What's Inside

Component	Count	Description
MCP Servers	11	Biological databases, compute (local + HPC + cloud), screening, campaign state, knowledge store
Agents	21	Research, design, screening, evaluation, lab integration, prior-art, sequence/structure/epitope researchers
Skills	19	BoltzGen, Protenix, PXDesign, scoring, screening, campaign management, HPC deployment, wet-lab feedback, mechanistic reasoning
Slash Commands	13	Campaign control from the Claude Code prompt

Server	Role
pdb	Protein Data Bank queries
uniprot	UniProt protein annotation
sabdab	Structural Antibody Database
screening	Screening battery orchestration
tamarind	Tamarind Bio cloud compute
cloud	Cloud compute abstraction
adaptyv	Adaptyv Bio lab submission (gated)
campaign	Campaign state management
research	Literature and target research
local_compute	Local GPU compute dispatch
knowledge	JSON-backed campaign knowledge store

Agent	Role
by-research	Target analysis, literature review, prior art (8-phase research pipeline)
by-prior-art-researcher	Prior-art deep dive for novel targets
by-sequence-researcher	Sequence-level analysis (orthologs, conservation, motifs)
by-structure-researcher	Structural analysis (PDB, AlphaFold, conformations)
by-epitope-researcher	Epitope-focused literature and structural research
by-research-synthesizer	Synthesize outputs from the research sub-agents
by-design	Generate designs via local, HPC, or cloud pipelines
by-screening	Score, filter, rank candidates
by-evaluator	Structural evaluation and quality assessment
by-visualization	Structure and results visualization
by-diversity	Sequence and structural diversity selection
by-campaign	Campaign lifecycle orchestration
by-knowledge	Learning system and campaign memory
by-verifier	Output verification and sanity checks
by-plan-checker	Campaign plan validation
by-environment	Environment setup and dependency checks
by-lab	Adaptyv Bio lab submission (triple-gated)
by-epitope	Epitope analysis and mapping
by-humanization	Antibody humanization engineering
by-liability-engineer	Sequence liability detection and fixes
by-formatter	Output formatting and reporting

Skill	Category	Description
boltzgen	tool	BoltzGen antibody/nanobody generation
protenix	tool	Protenix structure prediction (AF3-class)
pxdesign	tool	PXDesign de novo binder design
by-design-workflow	orchestration	Tool routing + intent → preset matrix
by-campaign-manager	orchestration	Campaign state, checkpoints, cost model
by-research	research	8-phase research pipeline with confidence tiers
by-database	research	PDB / UniProt / SAbDab lookups
by-epitope-analysis	research	Hotspot scoring + interface classification
by-hypothesis-debate	strategy	3+1 agent topology for novel-target strategy selection
by-scoring	scoring	ipSAE algorithm + composite scoring
by-screening	filtering	Full screening battery, liability + developability rules
by-failure-diagnosis	analysis	Mann-Whitney U statistical failure analysis
by-experiment-results	analysis	NEW. Ingest lab CSV/Excel, diagnose in-silico vs lab divergence, close design → screen → lab → learn loop
by-causal-reasoning	analysis	NEW. Evidence-anchored mechanistic hypotheses from knowledge graph
by-campaign-optimizer	optimization	Active learning + RF feature importance
by-knowledge	persistence	Campaign knowledge graph (entities + relationships)
by-session	session	Session init, config questionnaire, resume protocol
by-display	display	Canonical output formats (banners, score bars, status tables)
by-deploy-compute	deployment	NEW. Deploy Protenix / BoltzGen / PXDesign on local GPU, RunPod, Modal, or SLURM

See templates/.claude/skills/README.md for the canonical terminology table and full skill-linkage map.

Command	Action
/by:load	Load a campaign from file
/by:screen	Run screening battery on designs
/by:results	Display campaign results table
/by:watch	Live-watch running compute jobs
/by:status	Campaign status dashboard
/by:approve-lab	Approve Adaptyv Bio submission (gated)
/by:set-profile	Switch compute profile
/by:setup	Initialize environment and dependencies
/by:plan-campaign	Generate a detailed campaign plan
/by:welcome	Show welcome message and quick-start guide
/by:resume	Resume an interrupted or paused campaign

---

Setup

API Keys

Key	Required?	Where to get it	What it enables
RUNPOD_API_KEY	Optional	runpod.io	On-demand HPC GPU pods (~$0.40–$2.50/hr depending on GPU). Used by the by-deploy-compute skill.
TAMARIND_API_KEY	Optional	tamarind.bio (free account)	Cloud compute fallback — BoltzGen, Protenix, 200+ models. Free tier: 10 jobs/month
ADAPTYV_API_TOKEN	Optional	adaptyvbio.com	Lab testing submission (triple-gated)

Claude Code handles its own authentication. No separate Anthropic API key needed.

No keys needed for local-GPU mode — if you have an NVIDIA card with enough VRAM, BY can run the whole pipeline without any cloud service.

Configure your environment

After npx blatant-why init:

1. Copy .env.example to .env.
2. For local GPU (default) — set the tool paths:

   PROTEUS_FOLD_DIR=/path/to/Protenix
   PROTEUS_PROT_DIR=/path/to/PXDesign
   PROTEUS_AB_DIR=/path/to/boltzgen
   

3. For HPC (RunPod, Modal, SLURM) — add your provider key and let the by-deploy-compute skill handle deployment:

   RUNPOD_API_KEY=your_key_here   # or modal token, etc.
   

4. For Tamarind cloud fallback — add the API key:

   TAMARIND_API_KEY=your_key_here
   

5. For SSH remotes — add host configs to .by/config.json (compute.ssh_hosts).

The first-run questionnaire (run by the by-session skill on session open) walks through this interactively. Default compute.default_provider is "local"; priority order is ["local", "hpc", "tamarind"].

Compute Options

BY defaults to local GPU. The by-deploy-compute skill knows how to deploy Protenix / BoltzGen / PXDesign (and supplementary tools like AlphaFold, RFAntibody, ImmuneBuilder, ThermoMPNN, Boltz-2) on any of the targets below.

Provider	Cost	Setup	Best for
Local GPU (default)	Your hardware	Install tools + set env vars	Power users with GPUs
RunPod	~$0.40–$2.50/hr GPU pods	RUNPOD_API_KEY + by-deploy-compute	On-demand HPC bursts
Modal	Serverless, free tier	Modal token + by-deploy-compute	Cold-start-tolerant batch jobs
SSH Remote	Your infrastructure	Configure in .by/config.json	HPC clusters, in-house GPUs
Tamarind Bio	Free tier: 10 jobs/month	TAMARIND_API_KEY	Cloud fallback when no local GPU

1. Create a free account at tamarind.bio
2. Go to Settings → API Keys → Generate new key
3. Copy the key and add to .env:

   TAMARIND_API_KEY=your-key-here
   

4. That's it. BY will use Tamarind for all compute jobs.

Free tier: 10 jobs/month. Enough for a preview campaign (~5-10 designs). Paid tiers: Contact Tamarind for production pricing.

Tamarind provides access to 200+ structural biology tools including: