Skip to content

irit-mcp: tools for AI agents

irit-mcp is a Model Context Protocol server that gives AI agents (Claude Code, Claude Desktop and other MCP clients) the irit tools as typed tools. Each call runs the real sheetgen, leanqc, isotable, seqplan or dblock binary, and is written to a run record with a replay.sh that repeats the same commands without any AI.

It also wraps thirteen third-party tools, so a whole run is recorded and replayable the same way. For the microbial isolate path (trim, assemble, annotate, check quality, classify, type, find resistance genes): fastp, Shovill, Flye, Medaka, Bakta, CheckM2, GTDB-Tk, mlst and AMRFinderPlus, plus CoverM for the depth of an isolate by read mapping and Kleborate for Klebsiella typing, virulence and resistance scores. assembly_stats gives QUAST-style assembly statistics (N50, L50, N90, GC, Ns), computed by isotable. For metagenomes, from reads to metagenome-assembled genomes (MAGs): MEGAHIT, CoverM and MetaBAT2, then CheckM2 and GTDB-Tk on the bins. See Third-party tools.

Agents for bioinformatics fail in three documented ways (see landscape): they invent command-line flags, they carry on after a tool has refused bad input, and they leave no record that lets a result be reproduced without the AI. irit-mcp handles each one:

  • Invented flags. Every tool has a JSON schema with additionalProperties: false. An unknown parameter is refused before anything runs, and the error lists the parameters that do exist. Paths must exist, enums and ranges are checked, and database ids follow dblock’s own rules.
  • Carrying on after a failure. A non-zero exit comes back as an MCP error (isError: true) with the tool’s stderr and exit status, never as a result the agent could mistake for success.
  • No record. Every call goes into a run folder: exact argv, tool version, working folder, SHA-256 of every input and output, times, exit status. replay.sh re-runs the commands and checks each output’s hash against the record.

The server is a thin layer. It runs the binaries as subprocesses, so the CLI stays the single source of truth for what each tool does. The one exception: it links isotable’s output parsers, so the fastp, CheckM2, GTDB-Tk, mlst and AMRFinderPlus values it returns are read exactly as isotable grades them.

Build it (it is a standalone crate for now), and have the irit binaries on PATH or in a folder:

cargo build --release --manifest-path mcp/Cargo.toml # mcp/target/release/irit-mcp
cargo build --release -p sheetgen -p leanqc -p isotable -p dblock

Claude Code (the server runs in the folder Claude Code was started in):

claude mcp add irit -- /path/to/irit-mcp --bin-dir /path/to/irit/target/release

Any client that takes a JSON config (Claude Desktop’s claude_desktop_config.json, a project .mcp.json, …):

{
"mcpServers": {
"irit": {
"command": "/path/to/irit-mcp",
"args": ["--bin-dir", "/path/to/irit/target/release", "--runs-dir", "/data/project/irit-runs"]
}
}
}
Option Effect
--bin-dir DIR Folder holding the irit binaries (env IRIT_BIN_DIR). Default: search PATH.
--tool-path NAME=PATH Where a third-party tool is (fastp, shovill, flye, medaka_consensus, bakta, checkm2, gtdbtk, mlst, amrfinder, megahit, coverm, metabat2, kleborate, rasusa). Repeatable. Default: search PATH.
--runs-dir DIR Where run records go (env IRIT_RUNS_DIR). Default ./irit-runs.
--run-id ID Name of this session’s run folder. Default <UTC time>-<pid>. The server refuses to start when that folder already holds a record, so a second session can’t overwrite the first one’s.
--root DIR Folder the tools may write in. Default: the server’s working folder.
--allow-outside-root Turn the root check off, so tools can write anywhere the server’s user can. Not recommended.

Tools run in the server’s working folder, and relative paths in parameters are resolved there.

Every path a tool would write to must resolve inside the root: sheetgen output and link_into, leanqc outdir, isotable output and mqc, fastp out1, out2, json and html, Shovill, Bakta and CheckM2 outdir, GTDB-Tk out_dir and scratch_dir, mlst outfile, json and novel, AMRFinderPlus output, mutation_all, protein_output and nucleotide_output, dblock.toml and dblock.lock in the project_dir of dblock_add and dblock_fetch (the folder and each file are checked, since dblock writes through a symlinked dblock.toml), and dblock_add’s store. “Resolve” means after .. and symlinks, including a symlink that doesn’t point anywhere yet: qc -> /elsewhere or ../x.csv is refused, a symlink to a folder inside the root is fine. Absolute paths are accepted if they land inside the root.

leanqc writes its reports by name into outdir, so a symlink already in that folder (qc/s_leanqc.json -> /elsewhere) would be written through: the call is refused if any symlink in outdir resolves outside the root. sheetgen’s link_into is exempt: sheetgen only creates links there and never writes through an existing one.

A missing folder on the way to an output is created by the server just before the tool runs (trim/s1_R1.fastq.gz creates trim/; asm/s1 as Shovill’s outdir creates asm/). Only folders for checked outputs are created, so they are inside the root too; a file standing where a folder should be (reads.fq/out.json) is refused. The call’s record lists them as dirs, and replay.sh runs mkdir -p on them before the call, so a replay works from a clean folder.

The run records folder (--runs-dir, ./irit-runs by default, so usually inside the root) is never a valid target, even with --allow-outside-root: an output of irit-runs/<run>/replay.sh is refused.

Inputs (FASTQ files, results folders, sheets, schemas, catalogs, project_dir for the read-only dblock tools) may be anywhere the server can read.

Limits of these checks: they run before the tool starts, so a symlink created or swapped in between (by another process on the machine) is not caught; the server guards against a confused or misled agent, not against a local attacker racing it. Hard links (a file in the root that shares its data with one outside) are not detected.

The dblock store that comes from the environment (DBLOCK_STORE, else $XDG_DATA_HOME/dblock, else ~/.local/share/dblock) or from a store = line already in dblock.toml is not checked: it was chosen by whoever set up the machine or project, not by the agent.

Existing outputs are only replaced when the call says so:

  • sheetgen output, isotable output / mqc: an existing file (or symlink) is refused unless the call passes overwrite: true.
  • leanqc outdir: a folder that already has entries is refused unless overwrite: true; an empty or missing folder is fine.
  • sheetgen link_into has no overwrite: sheetgen itself refuses to replace a link that points elsewhere.
  • fastp, mlst and AMRFinderPlus outputs work like sheetgen output. Shovill, Bakta and CheckM2 outdir and GTDB-Tk out_dir work like leanqc outdir. Note that CheckM2 empties its outdir before it writes.
  • dblock_add and dblock_fetch update dblock.toml / dblock.lock in place, as dblock does. The transport is stdio; streamable HTTP is not built in yet.

Optional parameters can be left out; the tool’s own default then applies.

Sample sheet from folders of FASTQ files (sheetgen).

Parameter Type Meaning
dirs list of folders (required) Folders to scan recursively.
output file Write the sheet here (inside the root); otherwise it is only returned.
overwrite boolean Replace output if it exists. Default false.
format nfcore | qiime2 Layout when no schema is given.
pipeline owner/name Use this pipeline’s schema_input.json from Nextflow’s cache.
schema file Use this schema. Not together with pipeline.
set object Fixed column values, e.g. {"strandedness": "auto"}.
link_into folder Write clean symlinks there and list those.
name_from_dir, long, relative, no_pair_numeric, allow_merge, allow_unchecked booleans As the CLI flags.

Returns columns, rows (objects, up to 1,000), row_count and sheetgen’s notes in stderr.

Read QC (leanqc).

Parameter Type Meaning
files list of files (required) FASTQ/FASTA, plain or compressed.
outdir folder Default leanqc. Inside the root.
overwrite boolean Allow an outdir that already has files. Default false.
threads 1-64 Files processed at once.
dup_distinct integer Distinct sequences tracked for duplication.
phred 33 | 64 Quality encoding instead of detecting it.
no_html boolean JSON and TSV only.

Returns summary (files and counts per verdict) and per file: verdict, fails and warns (check name and detail), reads, mean_len, gc_percent, q30_percent, encoding warnings, and the JSON and HTML report paths. If leanqc exits 0 but no *_leanqc.json report appeared or changed in outdir, the result is an error (no_reports) rather than an empty summary.

One graded row per sample (isotable).

Parameter Type Meaning
dirs list of folders (required) Results folders. Include the folder holding Shovill’s outdirs: the assembly statistics come from each contigs.fa, and Shovill’s depth estimate from its shovill.log.
sheet file Sample sheet to join on (recommended).
mode isolate | mag Grading rules.
output, mqc files Also write the TSV / MultiQC table (inside the root).
overwrite boolean Replace output / mqc if they exist. Default false.
require list of reads, q30, contigs, n50, completeness, contamination, kraken, gtdb, depth, mlst, amr, kleborate Required measurements; [] turns the check off.
min_reads, max_contigs, min_n50 integers Thresholds.
min_q30, min_busco, min_completeness, max_contamination 0-100 Thresholds (%).
min_depth number Warn below this mean depth from read mapping (coverm_genome), fail below half. Default 20; 0 turns it off.

Returns counts per status and samples, each with status, reasons (a list) and values (the other columns).

QUAST-style statistics of assembly FASTA files (plain or gzip), computed by isotable (isotable assembly-stats --json, see isotable). Takes seconds, and is recorded and replayed like any call (its stdout, the JSON, is hash-checked).

Parameter Type Meaning
assemblies list of files (required) Shovill’s contigs.fa, Flye’s assembly.fasta, a reference genome, …
min_contig integer Contigs shorter than this are left out of every statistic except contigs_all and length_all. Default 500, QUAST’s default, so the numbers match a QUAST report on the same file. Always passed explicitly, so the record says which cut-off was used.

Returns assemblies, one object per file: assembly (the path as given), min_contig, contigs, total_length, largest_contig, n50, l50, n90, l90, gc_percent (G+C over A+C+G+T), ns_per_100kbp, contigs_1kb (contigs of 1000 bp or more), contigs_all and length_all (every contig). On the paper redo’s three K. pneumoniae Shovill assemblies it gave 71, 128 and 146 contigs in all and 38, 58 and 55 of 500 bp or more, N50 661,397, 364,313 and 304,235, as reported in the paper redo; Kleborate’s own contig statistics give the same N50.

Isolates per sequencing run at a target coverage (seqplan). Writes nothing.

Parameter Type Meaning
kit kit id (required) e.g. miseq-v3, nextseq-p1, novaseq-x-1.5b, minion-r10.4.1; seqplan --list-kits lists them.
reads e.g. 2x150 Read configuration. Default: the kit’s first listed one.
organism or genome_size preset id, or bp with k/M/G Exactly one. Presets use NCBI’s expected genome size.
coverage number Target mean coverage. Default 50.
usable, imbalance numbers Usable fraction of the run (default 0.8 Illumina, 1.0 nanopore) and barcode-imbalance margin (default 1.3).
samples integer Isolates to sequence: adds runs needed and cost per isolate for them.
run_price, currency number, label The user’s own run price. There are no built-in prices.

Returns plan: bases and read pairs per isolate, the kit’s output range with its basis and source, and isolates per run, runs and costs at both ends of the range (low, high).

Reference databases (dblock). All take project_dir (default: the working folder) and catalog (extra catalog JSON).

Tool Extra parameters Returns
dblock_catalog tool databases: id, download, on_disk, description, licence_note
dblock_add ids (required), store dblock’s message; dblock.toml in outputs
dblock_plan plan text: free space and fetch mode per database. Downloads nothing, but creates the (empty) store folder if missing, to measure its free space.
dblock_fetch confirm (required, must be true), ids, stream, keep_archive dblock’s message; dblock.lock in outputs
dblock_verify deep report
dblock_check report
dblock_env env (variable → path) and shell (export lines)

Runs sheetgen verify on read files or folders. It checks gzip integrity (every member, CRC and length), FASTQ structure, and MD5/SHA-256 against md5 files or ENA (ena, network, opt-in; runs names the accession for files whose name has none). The result has the per-file report. The call is an error (reads_have_problems) when any file is corrupt, doesn’t match, or is not listed, and the report is still there. The JSON report has timings, so replay.sh re-runs the check without comparing its output.

Runs cooccur on a genome × sample table (coverm_abundance’s output). Parameters: table, output (edge list TSV), summary (JSON; default next to the output), measure, taxonomy (GTDB-Tk summaries, for CPR labels), method (rho or spearman), min_prevalence, fdr, min_stat, positive_only, seed (default 1, so a replay matches). The result includes the summary, with the CPR–non-CPR pairs that pass.

Runs gtdbprep place: GTDB-Tk tree placement on the laptop data for genomes gtdbprep_ani didn’t assign. Parameters: genome_dir, extension, work, skip_assigned (gtdbprep_ani’s work folder), data_path (or $GTDBTK_DATA_PATH), env (GTDB-Tk 2.8.0 with gPlace, or $GTDBPREP_ENV), max_memory (default 6G), cpus. The result lists place.tsv’s rows. GTDB-Tk’s logs and the gPlace call log are volatile.

Nineteen tools wrap sixteen programs irit doesn’t ship. Each one is pinned to an upstream version: its parameters are exactly the flags that version has, read from its source at that release tag (for Shovill, mlst and AMRFinderPlus also compared with --help of the Bioconda package). Nothing else is offered, so an agent can’t pass a flag the program doesn’t know.

MCP tool Program Pinned version Flags read from Bioconda
fastp fastp 1.4.0 src/main.cpp fastp=1.4.0
shovill Shovill 1.4.2 bin/shovill (setOptions and the checks after it) shovill=1.4.2
flye Flye 2.9.6 (--version: 2.9.6-b1802) flye/main.py (the argparse block and _check_input) flye=2.9.6
medaka Medaka medaka_consensus 2.2.2 scripts/medaka_consensus (its getopts string) medaka=2.2.2
bakta Bakta 1.12.2 bakta/utils.py, DB check from bakta/db.py bakta=1.12.2
checkm2 CheckM2 predict 1.1.0 checkm2/main.py checkm2=1.1.0
gtdbtk_classify_wf GTDB-Tk classify_wf 2.8.0 gtdbtk/cli.py, data folders from config/common.py gtdbtk=2.8.0
mlst mlst 2.35.0 bin/mlst (setOptions and the main block) mlst=2.35.0
amrfinder AMRFinderPlus amrfinder 4.2.7 amrfinder.cpp, DB files from amrfinder_update.cpp and amrfinder_index.cpp ncbi-amrfinderplus=4.2.7
megahit MEGAHIT 1.2.9 src/megahit (parse_option) megahit=1.2.9
coverm_contig CoverM contig 0.8.0 src/cli.rs and coverm contig --full-help coverm=0.8.0
coverm_genome CoverM genome 0.8.0 src/cli.rs and coverm genome --full-help coverm=0.8.0
coverm_abundance CoverM genome 0.8.0 as coverm_genome coverm=0.8.0
semibin2 SemiBin2 single_easy_bin, and multi_easy_bin with multi 2.6.0 SemiBin2 single_easy_bin --help, SemiBin2 multi_easy_bin --help and SemiBin/main.py of the Bioconda package semibin=2.6.0
semibin2_concatenate SemiBin2 concatenate_fasta 2.6.0 SemiBin2 concatenate_fasta --help and concatenate_fasta in SemiBin/utils.py semibin=2.6.0
galah galah cluster 0.6.3 galah cluster --full-help of the Bioconda package (src/cluster_argument_parsing.rs) galah=0.6.3 with skani=0.4.0 (but see galah)
kleborate Kleborate 3.2.4 kleborate/__main__.py and kleborate --help of the pip package kleborate=3.2.4 (but see kleborate: pip is lighter)
metabat2 MetaBAT 2 2.18 metabat2 --help of the Bioconda package (MetaBAT) metabat2=2.18
rasusa Rasusa reads 5.1.0 rasusa reads --help of the Bioconda package (src/cli.rs) rasusa=5.1.0

Bioconda’s current Shovill is 1.4.2, not the older 1.1.0: 1.4.x added --plasmid, changed --mincov’s default to 2 and needs at least 8 GB for --ram.

How they work:

  • Finding the program. The server looks on PATH, or where --tool-path NAME=PATH says. If the program isn’t there, the call fails with tool_unavailable and an install hint, e.g. conda install -c conda-forge -c bioconda bakta=1.12.2. Nothing is run.
  • Versions. The first line of the program’s --version goes into the run record. If the version isn’t the pinned one, the call still runs, but its result has a warnings entry. Every result also has version and checked_against.
  • Warnings on stderr. Some warnings a tool prints still matter after a zero exit; they go into warnings (result and record): CheckM2’s scikit-learn InconsistentVersionWarning (models saved with another scikit-learn, which “might lead to … invalid results”) and AMRFinderPlus’s WARNING: lines, and gtdbprep’s warning: lines (a genome left out of the ANI screen). AMRFinderPlus from a conda environment that isn’t activated gets CONDA_PREFIX set to that environment (found from the program’s path), as activation would; the database is always passed with --database, so that doesn’t change which one is used.
  • Warnings from the outputs. Some results look fine by exit status but aren’t; these also go into warnings. All of them were seen in the depth experiment:
    • Shovill. Its genome-size estimate collapses at low depth (0.01–0.11 Mb for a 5.5 Mb genome at 5–10×). Shovill then subsamples the reads to that size and assembles a fragment, with exit 0. The server reads shovill.log and warns in three cases:

      • Shovill subsampled to a size under 1 Mb, or to more than twice the assembly.
      • The assembly is over twice the estimate. Shovill’s depth figure is then too high; the warning gives the real depth over the assembly.
      • gsize was given and the assembly is under 70% of it.

      A separate warning comes when the depth over the assembly is under 15×.

    • mlst. With no scheme, mlst picks one by best allele matches. When it then assigns no ST, the scheme may be another species’ (a fragmented K. pneumoniae got ecoli_achtman_4).

    • CheckM2. A call with more than 20 genomes warns before running. 48 genomes peaked at 7.7 GiB on an 8 GB laptop.

    • CoverM genome. When the assembly has a shovill.log beside it, Shovill’s depth estimate is compared with the mapped depth; a difference of more than 1.5× is a warning (Shovill divides by its own genome-size estimate unless given gsize).

    • Kleborate. An assembly with no row (its species check found no species Kleborate types), a species outside the K. pneumoniae species complex under the kpsc preset, a weak species match, and Kleborate’s own QC warnings (e.g. ambiguous_bases).

  • Checks before running. Inputs must exist and look right: FASTQ for fastp and Shovill, FASTA for Bakta, CheckM2, GTDB-Tk, mlst and AMRFinderPlus (plain or gzip; bzip2, xz and zstd are refused, and so is an empty file). Databases are checked for the files the program itself needs (below), so a wrong path fails in a second instead of after an hour.
  • Databases. Pass the path, or leave it out to use the variable the program reads (BAKTA_DB, CHECKM2DB, GTDBTK_DATA_PATH, AMRFINDER_DB, as set when the server started). With the variable unset too, the server uses the one database of that kind locked in dblock.lock in its working folder, and the result’s warnings names it; two candidates are refused. The server resolves it before running and records it. dblock_env shows the paths of databases that dblock manages. mlst’s PubMLST schemes come with the installed mlst (or $MLST_DBDIR): the server finds them from the program’s own path and hashes them into the record (below).
  • Failure. A non-zero exit is tool_failed, as for the irit tools. An exit status of 0 without the files the program always writes is missing_outputs: it is recorded as a failed call and replay.sh doesn’t rerun it.
  • Results. Each result has a small summary parsed from the outputs (below). fastp, CheckM2, GTDB-Tk, mlst and AMRFinderPlus outputs are read with isotable’s own parsers. If the summary can’t be read, the result is an error (output_unreadable), not an empty list.
  • Time. Shovill, Bakta, CheckM2 and GTDB-Tk can run for minutes to hours. The call returns when the program ends; an MCP client with a short request timeout may give up first.
  • Names isotable can join. isotable finds outputs by name and joins them by sample. Shovill always writes <outdir>/contigs.fa, which would make every assembly sample contigs, so: mlst’s outfile must contain mlst and end in .tsv, and with one assembly the sample part of the name (s1.mlst.tsv → s1) becomes mlst’s --label, the name in its FILE column; AMRFinderPlus’s output must contain amrfinder and end in .tsv, and isotable takes the sample from it (s1.amrfinder.tsv → s1); coverm_genome’s output must contain coverm and end in .tsv (s1.coverm.tsv → s1); Kleborate names its rows after the assembly file, so kleborate refuses contigs.fa and other fixed assembler names (use Shovill’s link_as, e.g. genomes/s1.fna). Other names are refused with a message saying why. isotable reads Shovill’s contigs.fa (when shovill.log is beside it) as the sample named after its folder (asm/s1 → s1), so name each outdir after its sample.

The large databases are not hashed into the run record (they are tens of GB). Only their small version files are: Bakta’s version.json, GTDB-Tk’s metadata/metadata.txt, AMRFinderPlus’s version.txt. Use dblock_verify to check a database itself. One exception: a GTDB-Tk skani/ database of at most 512 MB, such as the one gtdbprep_ani builds (9 MB for B. subtilis), is hashed into gtdbtk_classify_wf’s inputs, under the real path of its files, so the record says exactly which references the ANI screen compared against.

gtdbtk_classify_wf adds a warnings entry (in its result and its record) when data_path is neither inside a dblock store ($DBLOCK_STORE or the default, or a path in the working folder’s dblock.lock) nor a folder an earlier call of the same run wrote (gtdbprep_ani’s <work>/gtdbtk_data). The call still runs, but nothing in the record then says what that folder held beyond the files above, and replay.sh will use whatever it holds at replay time.

Trims and filters reads, and writes a JSON and an HTML report.

Parameter Type Meaning
in1 file (required) Read 1 FASTQ.
in2 file Read 2, for paired-end data.
out1, out2 files Trimmed reads. out2 needs in2 and out1; paired input with out1 needs out2.
json file (required) JSON report. Name it <sample>.fastp.json so isotable finds it.
html file HTML report. Default: json with .html.
overwrite boolean Replace existing outputs. Default false.
thread 1-16 Worker threads.
compression 1-9 gzip level for .gz outputs.
detect_adapter_for_pe, correction booleans Paired-end only.
adapter_sequence, adapter_sequence_r2 A/C/G/T/N Adapters, instead of detecting them.
disable_adapter_trimming, trim_poly_g, disable_trim_poly_g, cut_front, cut_tail, cut_right, dedup, overrepresentation_analysis, phred64 booleans As the fastp flags.
trim_front1, trim_tail1, cut_window_size (1-1000), cut_mean_quality (1-36), qualified_quality_phred, unqualified_percent_limit (0-100), n_base_limit, average_qual, length_required integers As the fastp options.
report_title text HTML report title.

Returns report (JSON and HTML paths) and summary: reads_raw, reads_trimmed, bases_trimmed, q30_trimmed (%), q30_bases and duplication (%).

Not offered: --stdin, --stdout, --interleaved_in, --unpaired1/2, splitting, UMI and merging options, and --dont_overwrite (the server enforces overwrite itself).

Assembles one isolate from paired-end Illumina reads.

Parameter Type Meaning
r1, r2 files (required) Read 1 and read 2 FASTQ (e.g. fastp’s out1, out2).
outdir folder (required) Output folder; the assembly is <outdir>/contigs.fa. One per sample.
overwrite boolean Allow an outdir that has files. Default false.
link_as file Also make this path (e.g. genomes/s1.fna) a relative link to <outdir>/contigs.fa, so CheckM2, GTDB-Tk and gtdbprep_ani name the genome after the sample. Recorded (links) and recreated by replay.sh (ln -sfn). Not inside outdir.
assembler spades, skesa, megahit, velvet Default spades.
gsize text Genome size like 2.8M, 4500K, 5000000. Default: estimated from the reads.
depth integer Sub-sample to this depth; 0 turns it off. Default 150.
minlen, mincov numbers Drop short or low-coverage contigs; 0 lets Shovill choose.
namefmt text Contig names, one counter like s1_%05d.
cpus integer
ram number, at least 8 GB; Shovill 1.4.2 refuses less than 8 and more than the machine has.
plasmid boolean SPAdes plasmid mode (assembler: spades only).
kmers text Comma-separated k-mer sizes, e.g. 31,55,77.
trim, noreadcorr, nostitch, nocorr, keepfiles booleans As the Shovill flags. nocorr skips Pilon, the slowest step.

The server always sends --force (Shovill refuses any existing folder without it, even an empty one) and refuses an outdir whose absolute path has spaces or shell characters: Shovill pastes it unquoted into a shell command. Returns contigs_file and assembly: contigs, total_length, n50, longest and gc_percent, counted from contigs.fa. Every output is volatile: contigs.fa headers carry the date (date=YYYYMMDD), and neither SPAdes nor SKESA gave the same assembly twice from identical reads in every test (see the volatile table). The contig count, total length and N50 go into the run record (assembly), and replay.sh prints the replayed assembly’s beside them. isotable reads contigs.fa itself (contigs, length, N50, counted as QUAST does), so give it the folder that holds the outdirs.

Not offered: --opts (free text pasted into the assembler’s shell command), --tmpdir (Shovill makes its own), --check.

Assembles one isolate from long reads: ONT R10.4.1 reads basecalled with hac or sup (the default read_type, nano-hq), older ONT reads, or PacBio. See Nanopore reads to isolate results on a laptop for a measured run.

Parameter Type Meaning
reads list of files (required) Long-read FASTQ or FASTA files of one isolate (plain or gzip).
read_type nano-hq, nano-raw, nano-corr, pacbio-hifi, pacbio-raw, pacbio-corr Default nano-hq.
outdir folder (required) Output folder; the assembly is <outdir>/assembly.fasta. One per sample.
overwrite boolean Allow an outdir that has files (Flye then continues from them; prefer an empty folder).
link_as file As Shovill’s: a link named after the sample to <outdir>/assembly.fasta.
genome_size text Like 5.5m or 5000000. Needed for asm_coverage.
asm_coverage integer Use only the longest reads up to this depth for the first stage. Not with meta.
threads, iterations, min_overlap, read_error numbers As the Flye flags.
meta, keep_haplotypes, no_alt_contigs, scaffold booleans As the Flye flags.
deterministic boolean Build disjointigs single-threaded so identical runs give identical assemblies (slower).

Returns assembly_file, assembly (contigs, total_length, n50, longest, gc_percent) and contigs: per contig its length, depth and whether Flye closed it into a circle, from assembly_info.txt. A complete bacterial genome is one circular chromosome plus circular plasmids. Every output is volatile (multi-threaded runs differ; flye.log has times); the contig count, length and N50 go into the run record, as for Shovill. isotable reads assembly.fasta when flye.log is beside it.

Small plasmids. Default mode missed a 4,999 bp resistance plasmid at 11x (chromosome 98x) that meta found, and Flye closed several small plasmids as two or three copies in one circle. For each circular contig up to 300 kb, irit-mcp measures how much of its sequence (21-mers) occurs more than once in it. Above half, it warns that genes there are counted more than once and the length isn’t the plasmid’s. On the nanopore runs, multi-copy contigs scored 0.92–1.0 and all others at most 0.2 (measurements).

Deep data. asm_coverage limits only the first stage: the later stages map every read. On the laptop, K. pneumoniae AF38 (5.7 Mb, 2.58 Gb of reads, about 450x) went over the 8 GB cap in Flye’s consensus stage with asm_coverage 50 and was killed. Subsample deep data with rasusa first (this project uses 100x).

Not offered: --extra-params (free text into Flye’s configuration), --resume, --resume-from, --stop-after, --polish-target, and the deprecated --subassemblies, --plasmids, --trestle and --hifi-error.

Randomly subsamples reads to a target, for deep long-read data before Flye or to test how results hold at lower depth. Rasusa (Hall, JOSS 2022, doi:10.21105/joss.03941).

Parameter Type Meaning
reads list of files (required) One FASTQ/FASTA file, or read 1 then read 2 of a pair (pairs are kept together). Plain or gzip.
outputs list of files (required) One per input, same order; .gz gives gzip.
coverage + genome_size number + text Target depth, e.g. 100 and 5.7mb.
bases text Target bases, e.g. 570mb.
num integer Target reads (of each file for a pair).
frac number Target fraction, above 0 and at most 1.
seed integer Default 1, so the same call keeps the same reads.
overwrite boolean Replace existing outputs.

Give exactly one of coverage, bases, num and frac. With the same seed the output is byte-identical (checked on 2,000 reads of AHB29: same MD5 twice), so the outputs are not volatile and replay.sh compares their hashes. Returns output_files.

Not offered: --one-pass / --probability (approximate counts), --strict, alignment formats, and the compression and format overrides (the file name decides).

Polishes a long-read draft (Flye’s assembly.fasta) with the same reads, using medaka_consensus.

Parameter Type Meaning
reads file (required) The long reads (FASTQ or FASTA).
draft file (required) The draft assembly FASTA.
outdir folder (required) Must be empty; the result is <outdir>/consensus.fasta.
link_as, overwrite file, boolean As Flye’s; overwrite only replaces the link.
model text A medaka model, e.g. r1041_e82_400bps_bacterial_methylation. Needed when the read headers don’t name the basecalling model, which is the case for many archive downloads.
bacteria boolean --bacteria: pick the bacterial model from the read headers.
threads, batch_size integers As -t and -b. batch_size sets memory use (Medaka’s default 100 peaked at 7.36 GiB on a 6 Mb genome; 50 at 4.78 GiB and 25 at 3.66 GiB, with the same consensus and no slower). Use 50 or 25 on 8 GB machines.

medaka_consensus is a bash script with short options only, so its arguments are separate words (-i reads.fq), and a path starting with - gets ./ in front. Its version comes from medaka --version beside it. Returns assembly_file and assembly for consensus.fasta, and model_file. Medaka downloads a named model the first time it is used (into its package’s data/ folder), so the server reads the model file Medaka logged (“Using model: …”). It adds that file to the call’s inputs with its SHA-256, and replay.sh notes it. isotable reads consensus.fasta when consensus_probs.hdf is beside it, and then leaves out the Flye draft of the same sample.

Not offered: -f (reuses or replaces old intermediate files; the server wants an empty outdir instead), -x, -B, -M, -p, -g, -r and -q.

Annotates one genome assembly.

Parameter Type Meaning
genome file (required) Assembly, FASTA.
db folder Bakta database (with version.json). Default $BAKTA_DB.
outdir folder (required) Output folder.
overwrite boolean Allow an outdir that has files. Default false.
prefix name Output file prefix. Default: the genome file name without its last extension, as Bakta does.
genus, species, strain, plasmid text Organism.
translation_table 11, 4 or 25
gram positive, negative, unknown Sent as +, -, ?.
locus, locus_tag text Checked with Bakta’s own rules.
min_contig_length, threads integers
complete, keep_contig_headers, compliant, meta booleans As the Bakta flags.
skip list of trna, tmrna, rrna, ncrna, ncrna_region, crispr, cds, pseudo, sorf, gap, ori, filter, plot Sent as --skip-<step>.

The database check follows Bakta 1.12.2’s own: version.json with date, major, minor and type; major version 6; and all the files Bakta opens, including psc.dmnd (full) or pscc.dmnd (light). dblock’s bakta-db-v6-full and bakta-db-v6-light pass.

The server always sends --force (Bakta refuses an existing folder without it), and always sends --prefix, so the output names are known. Returns summary_file and summary, the numbers from <prefix>.txt: sequences (length, count, gc, n50, …), annotation (cdss, trnas, rrnas, hypotheticals, …) and bakta (software and database version).

Not offered: --proteins, --hmms, --regions, --replicons, --prodigal-tf, --tmp-dir, --debug, --verbose.

Completeness and contamination of genomes or MAGs (checkm2 predict).

Parameter Type Meaning
genomes list of files FASTA files. Give this or genome_dir.
genome_dir folder Folder of FASTA files.
extension text With genome_dir: which files. Default .fna.
outdir folder (required) Output folder.
overwrite boolean Allow an outdir that has files. CheckM2 then deletes them first.
db file or folder The DIAMOND .dmnd file, or a folder with exactly one. Default $CHECKM2DB.
threads integer
model auto, general, specific, both both is --allmodels.
lowmem boolean Less RAM, slower. Use on 8-16 GB machines.
ttable integer Translation table, from the list CheckM2 accepts.
genes, remove_intermediates booleans As the CheckM2 flags.

The server always sends --force, since CheckM2 refuses a non-empty folder without it. Returns report (the quality_report.tsv path) and genomes: genome, completeness, contamination.

GTDB taxonomy for the genomes in a folder.

Parameter Type Meaning
genome_dir folder (required) One genome per file.
extension text Default fna; use fna.gz for gzipped files.
out_dir folder (required) Output folder.
overwrite boolean Allow an out_dir that has files.
data_path folder GTDB-Tk reference data (the release folder). Default $GTDBTK_DATA_PATH. Sent to GTDB-Tk as GTDBTK_DATA_PATH and recorded in env.
prefix name Default gtdbtk.
cpus, pplacer_cpus integers Use pplacer_cpus: 1 on a laptop.
scratch_dir folder pplacer writes a memory-mapped file here: much less RAM, slower.
full_tree, place_species, keep_intermediates, write_single_copy_genes, genes booleans As the GTDB-Tk flags.
force boolean GTDB-Tk’s --force: carry on when one genome fails. It does not mean overwrite.
min_af 0-1 Minimum alignment fraction for a species match.
min_perc_aa 0-100 Minimum % of amino acids in the MSA.

The data check reads metadata/metadata.txt (it must have VERSION_DATA) and wants the folders classify_wf reads: markers, masks, metadata, mrca_red, pplacer, radii, split, taxonomy and skani.

Returns summary_files and genomes: genome, gtdb (classification) and, when GTDB-Tk filled them, classification_method, closest_genome_reference, closest_genome_ani, msa_percent, warnings and note. Only summaries written by this call are read, so a stale ar53 file from an earlier run is ignored.

Laptop options in GTDB-Tk 2.8.0, checked against the research notes:

  • --scratch_dir and --pplacer_cpus exist, and are offered.
  • No --skip_ani_screen. Since 2.7, classify_wf always runs the skani ANI screen first, and no command-line option skips it. So the placement-only data (dblock gtdbtk-r232-placement, no skani/) can’t run classify_wf by itself: the server refuses it and points to gtdbprep_ani, whose <work>/gtdbtk_data adds a small skani database, and to the placement test for genomes the screen doesn’t assign.
  • The split tree needs its files. Unless full_tree is set, the data must hold split/backbone/pplacer/gtdbtk_package_backbone.refpkg and split/class_level/tree_mapping.tsv. Without them pplacer would fail after the ANI screen and marker steps, so the server refuses first. GTDB’s mock database has an empty split/ and needs full_tree: true.
  • No --max_memory. That is a gPlace option. GTDB-Tk calls pplacer by name, so gPlace is used through a pplacer shim on PATH (see the same page), not through a GTDB-Tk flag.
  • --mash_db went away in GTDB-Tk 2.5.0 (skani replaced Mash) and isn’t offered.

The laptop route to a GTDB species: gtdbprep ani screens the genomes locally, fetches only the reference sketches skani would compare (into a per-user cache), and runs GTDB-Tk’s own ANI screen on them. It needs GTDB-Tk 2.8 with skani 0.3.1, the screen index and the placement-lite data, not the 85 GB skani database. This is an irit binary, so it comes from --bin-dir or PATH like sheetgen.

Parameter Type Meaning
genome_dir folder (required) One genome per file; the file name is the genome’s name.
extension text Default fna.
index folder Screen index: meta.json, refs.bin, markers.idx (dblock gtdbtk-r232-ani-screen). Default: the ANI-screen index locked in ./dblock.lock.
data_path folder GTDB-Tk data with taxonomy/, radii/, metadata/ (dblock gtdbtk-r232-placement-lite). Default $GTDBTK_DATA_PATH; sent as --data.
work folder (required) Work folder inside the root.
overwrite boolean Allow a work folder that has files.
source text Where sketches missing from the cache come from: a path or URL of an unpacked sketches.db, a URL with {part} (with part_size), or gtdb (range reads of GTDB’s own archive). Network; ask the user first. Omit when everything is cached.
part_size integer Bytes per part, for a {part} source only.
cache folder Default $XDG_CACHE_HOME/irit/gtdbprep-ani, else ~/.cache/irit/gtdbprep-ani, resolved when the server starts and sent as --cache.
skani file or name Default: skani in the GTDB-Tk environment or on PATH.
species_only boolean Fetch only references that could give the species call: same species, fewer downloads.
fetch_jobs 1-16 Range requests at once.
env folder Conda/micromamba environment with GTDB-Tk 2.8. Default $GTDBPREP_ENV; sent as --env.
cpus integer Default 4.

The sketch cache may be outside the root, unlike other outputs: it is shared by every run on the machine, and gtdbprep only adds sketches it has checked against the index. It may not be inside the run records. The record hashes the genomes, the index’s meta.json and refs.bin (not the 1.7 GB markers.idx: dblock verify covers it) and the three data files the screen reads. *.log and the gzip file are volatile; everything else in work was identical in two runs. The cache isn’t part of the record, so on another machine replay.sh fetches the sketches again from the recorded --source (GTDB’s server for gtdb), or fails without one; a comment above the call in replay.sh says which. When sketches are missing and no source is given, the error says how many and how many MB, so the network use can be weighed before allowing it.

Returns genomes (per genome: assigned_by_ani, species, taxonomy, reference, ani, af, markers, candidates, and used with species_only; a genome skani could not sketch has screened: false and a note), warnings, stdout (gtdbprep’s own lines: sketches cached and fetched, times) and data_path_for_classify. That folder, <work>/gtdbtk_data, is a complete GTDB-Tk data folder: links to the placement-lite data plus the small skani database. Passed as gtdbtk_classify_wf’s data_path, it gives GTDB-Tk’s usual summary files, and since it is an output of a recorded call, the record shows where it came from:

{"name": "gtdbprep_ani", "arguments": {"genome_dir": "genomes", "index": "/db/gtdbtk-r232-ani-screen/ani-screen-r232",
"work": "ani/w", "species_only": true}}
{"name": "gtdbtk_classify_wf", "arguments": {"genome_dir": "genomes", "data_path": "ani/w/gtdbtk_data",
"out_dir": "gtdbtk", "pplacer_cpus": 1}}

On the B. subtilis 168 assembly from the laptop run, with every sketch cached: gtdbprep_ani took 15 s (s__Bacillus subtilis, GCF_000009045.1, ANI 100), then gtdbtk_classify_wf 4.8 s (classification_method: ani_screen). After deleting both output folders, replay.sh recreated them and matched all 32 outputs.

A genome the screen does not assign still needs tree placement, which classify_wf on this data can’t do on a laptop yet (gPlace through a pplacer shim; see the placement test).

Multi-locus sequence type of assemblies, with the PubMLST schemes bundled with mlst.

Parameter Type Meaning
contigs list of files (required) Assemblies, FASTA. Usually one: Shovill’s contigs.fa.
outfile file (required) Tab-separated table. Must contain mlst and end in .tsv; name it <sample>.mlst.tsv.
overwrite boolean Replace existing outputs. Default false.
label text Name in the FILE column instead of the path; one assembly only. Default: the sample part of outfile.
json, novel files Also write JSON / novel alleles (FASTA).
scheme name Force a scheme, e.g. saureus, ecoli_achtman_4 (mlst then sets minscore to 0).
full boolean Header row plus STATUS and SCORE columns; isotable reads this layout too.
minid, mincov, minscore 0-100 As the mlst options.
threads integer BLAST threads.

Returns outfile and results, one per assembly: sample (the name isotable joins on), file, scheme, st and alleles (with full: the table’s own columns). mlst marks a novel allele ~ and a partial one ?, and gives ST - when no scheme matched. database_version is the date in the data’s VERSION.txt (2025-12-29 for Bioconda’s mlst 2.35.0).

The PubMLST data mlst types with is part of the record. mlst 2.35.0 reads it from $MLST_DBDIR, or else from db/ next to the real path of the mlst script (Bioconda’s layout). After locating the program, the server asks it where (mlst --help prints the resolved --datadir and --blastdb, so a wrapper script in front of mlst is followed; if it prints none, db/ next to the program’s real path is used) and hashes VERSION.txt, scheme_species_map.tab, the BLAST database of every allele (blast/mlst.fa.*) and each scheme’s profile table (pubmlst/<scheme>/<scheme>.txt): about 180 files. The allele files themselves are covered by the BLAST database built from them. A set $MLST_DBDIR is recorded and exported by replay.sh.

Not offered: --csv and --legacy (isotable reads the tab-separated layout), --blastdb and --datadir (the schemes come with the installed mlst, or $MLST_DBDIR), --fofn, --exclude, and the listing options (--list, --longlist, --info, --check).

Antimicrobial resistance genes and point mutations with AMRFinderPlus.

Parameter Type Meaning
nucleotide file Assembly, FASTA.
protein file Proteins, FASTA (e.g. Bakta’s <prefix>.faa). Give nucleotide, protein or both.
gff file Protein locations (e.g. Bakta’s <prefix>.gff3). Needs protein; required with both inputs.
annotation_format bakta, genbank, microscope, patric, pgap, prodigal, prokka, pseudomonasdb, rast, standard Which tool wrote the GFF. Needs gff.
database folder AMRFinderPlus database. Default $AMRFINDER_DB.
organism name E.g. Escherichia, Staphylococcus_aureus: point mutations and organism-specific genes. Checked against the database.
plus boolean Also virulence, stress and other “plus” genes.
report_common boolean Needs organism and plus.
report_all_equal, print_node booleans As the flags.
ident_min -1 or 0-1 -1 (default): curated cut-offs.
coverage_min 0-1 Default 0.5.
translation_table 1-33 Default 11.
name text Adds a first Name column with this text.
output file (required) Report. Must contain amrfinder and end in .tsv; name it <sample>.amrfinder.tsv.
mutation_all, protein_output, nucleotide_output files Need organism, protein, nucleotide respectively.
threads integer
overwrite boolean Replace existing outputs. Default false.

The database check follows amrfinder 4.2.7’s own: the folder has version.txt and the other files amrfinder_update downloads (AMR.LIB, AMRProt.fa, AMR_CDS.fa, fam.tsv, taxgroup.tsv, …); it is indexed (AMRProt.fa.phr, AMR.LIB.h3m, AMR_CDS.fa.nin, and with organism and a nucleotide input the organism’s AMR_DNA-<organism>.fa BLAST index); database_format_version.txt is not newer than 4.2.7; and the data version is at least 2025-09-22.2 (dataVer_min in amrfinder.cpp). An unindexed folder (the raw files from NCBI) is refused with a hint to run amrfinder_index or to fetch it with dblock, which indexes it. dblock’s amrfinderplus-db-4.2-2026-10-29.1 passes.

Returns database_version, report and summary: amr_genes (what isotable reports), counts_by_type (AMR, STRESS, VIRULENCE, …) and hits, each with element_symbol, element_name, type, subtype, class, subclass, method, contig_id or protein_id, coverage_of_reference and identity_to_reference.

Not offered: --update and --force_update (they change the database outside the record; fetch a pinned one with dblock instead), --blast_bin, --hmmer_bin, --pgap, --gpipe_org, --parm (NCBI’s testing options), --debug, --log, --quiet, --list_organisms, --database_version and --nucleotide_flank5_output / _size.

Typing of Klebsiella (and Escherichia) assemblies with Kleborate 3. The default kpsc preset (K. pneumoniae species complex) runs Kleborate’s species check (Mash), then MLST, the yersiniabactin (ybt), colibactin (clb), aerobactin (iuc), salmochelin (iro) and rmpADC loci, rmpA2, the virulence and resistance scores, acquired resistance genes and mutations, a ciprofloxacin prediction, wzi and Kaptive’s K and O loci. Needs mash and minimap2 on PATH.

Parameter Type Meaning
assemblies list of files (required) FASTA (plain or gzip), named after the samples: Kleborate names each row after the file without its extension. contigs.fa, assembly.fasta and the like are refused; two files with the same name too.
outdir folder (required) Output folder; an existing one with files needs overwrite.
preset kpsc, kosc, escherichia Default kpsc (unless modules is given alone). escherichia runs ECTyper, whose first run downloads about 900 MB.
modules list of module names More modules, or (without preset) only these; kleborate --list_modules lists them. Kleborate then names its table <first module>_output.txt, which isotable doesn’t read.
overwrite boolean Default false.

Kleborate 3.2.4 writes each assembly to the table of its species, whatever the preset: klebsiella_pneumo_complex_output.txt (KpSC), klebsiella_oxytoca_complex_output.txt or escherichia_output.txt; typing columns of a species the preset doesn’t cover say Not Tested. An assembly of any other species gets no row (Kleborate prints “does not match any specified species” and skips it). So no table is required of a call; the result’s warnings name the assemblies without a row, and those outside the KpSC under kpsc.

Returns tables (the ones the call wrote) and assemblies, one object per row: strain, table, species, species_match, QC_warnings, ST, virulence_score, resistance_score, num_resistance_classes, num_resistance_genes, Yersiniabactin/YbST, Colibactin/CbST, Aerobactin/AbST, Salmochelin/SmST, RmpADC/RmST, rmpA2, K_locus, K_type, K_locus_confidence, K_locus_identity, the same four for the O locus, and amr: the resistance columns that found something (e.g. Bla_ESBL_acquired: CTX-M-15). - means not found.

Kleborate’s databases ship inside its Python package (kleborate/modules/*/data: Mash sketches, MLST alleles and profiles, AMR genes) and Kaptive’s (kaptive/data, the K and O locus references). The server finds them from the program’s path (<prefix>/lib/python3.*/site-packages, following a shell wrapper that execs the real script) and hashes them into the record with Kaptive’s METADATA (its version): 117 files for the pip install. bundled_data_files_hashed says how many; when none are found, a warning says so.

Install: Bioconda’s kleborate=3.2.4 also installs ECTyper, whose post-link script downloads a 900 MB Mash sketch. pip’s (pip install kleborate==3.2.4) doesn’t, but needs pandas added and Kaptive 3.2.x: Kleborate 3.2.4 imports kaptive.database, which Kaptive 3.3 no longer has (pip install kleborate==3.2.4 kaptive==3.2.2 pandas, with mash and minimap2 from Bioconda), as the real-tools workflow does. --outdir is passed as a word of its own: Kleborate looks for --outdir in its arguments before parsing them and refuses --outdir=x.

Measured on the laptop (2026-11-14, pip install, 4 GB cap): 34-40 s per K. pneumoniae assembly. BfR-EC-20867 from the paper redo: K. pneumoniae (strong match), ST716 (the paper’s), ybt 14 on ICEKp12 (the paper reports ybt in this isolate) and no clb, iuc, iro or rmpADC, virulence score 1, resistance score 1, K locus KL110 and O locus OL2α.1 (both “Typeable”). Its resistance genes match Table 1 except blaTEM-1, which Kleborate didn’t report. Two runs gave byte-identical tables (replay.sh matched them). Not offered: --resume, --trim_headers (isotable reads either; full headers name the module) and the per-module options of --help_all.

Assembles a metagenome (one sample, or several as a co-assembly) for binning. Writes <outdir>/final.contigs.fa.

Parameter Type Meaning
r1, r2 lists of files Paired reads (FASTQ, plain or gzip), paired in order. Several runs of one sample go in one call.
single list of files Single-end or merged reads.
outdir folder (required) Output folder; an existing one with files needs overwrite.
memory_gb number, 0.5-4096 Memory for building the de Bruijn graph. Default 4: MEGAHIT’s own default is 90% of the machine’s RAM, which ignores a memory cap (cgroup, container) and gets the process killed under one. Keep it below the cap. Passed in bytes, since a value below 1 would be read as a fraction.
threads integer MEGAHIT’s default is every logical CPU.
presets meta-sensitive or meta-large MEGAHIT’s presets (more k-mers for low-coverage members; or large, complex samples such as soil).
k_list text Ascending odd k-mer sizes in 15-255, steps of at most 28, e.g. 21,29,39,59,79,99,119,141.
min_contig_len, min_count integers Shortest contig written (default 200); minimum (k+1)-mer multiplicity (default 2).

The server always sends --force (MEGAHIT refuses any existing folder without it, even an empty one; it only skips that check) and refuses a read file with a comma in its name (MEGAHIT splits the lists on commas). Every output is volatile, as with Shovill: the log has times, and the contigs aren’t known to be byte-identical between runs. The contig count, length and N50 are recorded instead, and replay prints them beside the replayed assembly’s. Not offered: --continue, --tmp-dir (MEGAHIT writes under outdir), --keep-tmp-files, --no-hw-accel, --mem-flag and the graph-cleaning options.

The bins’ taxonomy: gtdbprep_ani assigns bins of known species. GTDB-Tk’s classify_wf can’t place the rest on dblock’s gtdbtk-r232-placement-lite data: it always aligns against GTDB’s reference MSA, which placement-lite leaves out, and fails with msa/gtdb_r232_bac120.faa does not exist. Until that is solved, place them with the full GTDB-Tk data, or outside irit-mcp with gtdbtk identify, gtdbtk align --skip_gtdb_refs and classify with the ANI screen skipped (see the MAG laptop test).

Maps each sample’s reads to the contigs and writes a per-contig coverage table. With methods: ["metabat"] the table is MetaBAT2’s depth input (contigName, contigLen, totalAvgDepth, then depth and variance per sample). CoverM then counts only reads of at least 97% identity, as MetaBAT’s own jgi_summarize_bam_contig_depths does.

Parameter Type Meaning
reference file (required) Contigs, FASTA: MEGAHIT’s final.contigs.fa.
r1, r2 lists of files One read pair per sample. Each pair is a column; more samples help binning (differential coverage).
single list of files Single-end FASTQ, one per sample (ENA serves some runs only that way); a column each, after the pairs. Give r1/r2, single, or both.
output file (required) The table (TSV).
mapper strobealign (default), minimap2-sr, bwa-mem The aligner CoverM runs.
methods list mean (CoverM’s default), trimmed_mean, covered_fraction, covered_bases, variance, length, count, reads_per_base, rpkm, tpm, or metabat on its own.
min_read_percent_identity, min_read_aligned_percent percentages Read filters.
threads integer CoverM’s default is 1.
bam_cache_dir folder Also keep each sample’s BAM (--bam-file-cache-directory): <folder>/<reference file name>.<read 1 file name>.bam, sorted by coordinate. These are the bams of semibin2. Two samples whose read 1 files have the same name are refused (they would share a BAM).

Returns the number of contigs in the table and, per sample, the reads mapped and their percentage from CoverM’s log, and the BAM paths with bam_cache_dir. A cached BAM’s header records the temporary folder CoverM sorted in (samtools sort -T /tmp/coverm_fifo.<random>/...), so its bytes differ between identical runs: BAMs are volatile outputs, and replay.sh says that a later call read a BAM that differs (the alignments don’t). Measured (2026-11-14, this project’s laptop, 8 GB cap, 6 threads): the Crystal Geyser sample’s 9.7 million trimmed reads with bam_cache_dir in 104 s at 4.69 GiB (cgroup peak), a 1.05 GB BAM; the depth table was byte-identical to the one of the earlier run without the cache. Not offered: BAM input (--bam-files), --cache-unfiltered-bam-files, --discard-unmapped, the --*-params options (free text passed to the aligner), sharding and pre-built indexes.

The depth of an isolate by read mapping: maps the isolate’s paired reads to its own assembly (coverm genome --single-genome, all contigs one genome) and writes a table of the mean depth and the fraction of the assembly covered. Shovill’s own figure (“Estimated sequencing depth”) is read bases over the genome size it used, its own k-mer estimate unless gsize was given; in the depth experiment it was about 3× too high at 20× without gsize.

Parameter Type Meaning
assembly file (required) The isolate’s assembly, e.g. Shovill’s contigs.fa.
r1, r2 files (required) The isolate’s reads (FASTQ, plain or gzip), e.g. fastp’s trimmed reads.
output file (required) The table (TSV). Must contain coverm and end in .tsv; name it <sample>.coverm.tsv.
mapper strobealign (default), minimap2-sr, bwa-mem The aligner CoverM runs.
min_read_percent_identity, min_read_aligned_percent percentages Read filters. Default 0.
threads integer CoverM’s default is 1.
overwrite boolean Default false.

The methods are fixed: mean (CoverM’s mean leaves out 75 bp at each contig end) and covered_fraction. --min-covered-fraction=0 is always passed: CoverM’s default (10%) reports a genome covered less than that as depth 0, which would hide a wrong pairing of reads and assembly. Returns genomes (per genome: sample, the name isotable joins on, mapped_depth and covered_fraction in %) and mapped (reads mapped and their percentage, from CoverM’s log), and a warning when a shovill.log beside the assembly gives a depth more than 1.5× off.

Measured on the laptop (2026-11-14): BfR-EC-20867’s trimmed MiSeq reads (1.4 million) on its Shovill assembly in 26 s, 4 threads, under a 4 GB cap: 50.34× mean depth, 99.99% of the assembly covered, 99.99% of reads mapped. Shovill had estimated 51×; the paper reports 49.0×. Two runs gave the same table.

Bins the contigs into genomes by depth and tetranucleotide frequency. Writes <outdir>/<prefix>.<n>.fa, one FASTA per bin, ready for checkm2 (genome_dir the outdir, extension fa), gtdbprep_ani and gtdbtk_classify_wf, and then isotable with mode: mag.

Parameter Type Meaning
contigs file (required) The assembly, FASTA.
depth file coverm_contig’s metabat table (its header is checked). Without it MetaBAT2 bins on tetranucleotide frequency alone, which works poorly.
outdir folder (required) Folder for the bins; created by the server.
prefix text Bin name prefix, default bin.
min_contig integer, at least 1500 Shortest contig binned (default 2500).
min_bin_size integer Smallest bin written, in bp (default 200000).
seed integer, 1 or more Default 1 here: MetaBAT2’s own default (0) draws a random seed, so its bins would differ between runs.
threads integer MetaBAT2’s default is every core.
unbinned, no_sample_depths booleans Also write <prefix>.unbinned.fa; leave per-sample depths out of the bin headers.

Returns each bin’s contigs, length, N50 and GC, the bin count and the binned length. MetaBAT2 has no --version, so the version is the first line of its --help (on stderr), in the record and in replay.sh’s version check. It fails (exit 1, “no large target contigs”) when no contig reaches min_contig.

Bins one sample’s contigs with SemiBin2 (SemiBin2 single_easy_bin), a binner that embeds contigs with a neural network before clustering them. Writes <outdir>/output_bins/<tag>_<n>.fa (plain FASTA) and <outdir>/contig_bins.tsv. Two ways to run it:

  • A pretrained model (environment) with depth, coverm_contig’s metabat table of this one sample, or with one BAM. SemiBin2 2.6.0 ships models for human_gut, dog_gut, cat_gut, mouse_gut, pig_gut, chicken_caecum, human_oral, ocean, soil, built_environment, wastewater and global (get_model_path in its utils.py); use global when none matches. SemiBin2 only accepts a MetaBAT depth table together with a pretrained model, and only a single-sample one.
  • Its own model, trained on this sample (self-supervised), from bams: one sorted BAM per sample, all mapped to these contigs, which coverm_contig keeps with bam_cache_dir. This did not fit in 8 GB (below).
  • Several samples binned together (multi, SemiBin2 multi_easy_bin): see Multi-sample binning below.
Parameter Type Meaning
contigs file (required) One sample’s assembly, FASTA. With multi, semibin2_concatenate’s concatenated.fa.
outdir folder (required) Output folder; one with files needs overwrite (SemiBin2 replaces output_bins/ and its tables).
multi boolean Multi-sample binning (multi_easy_bin). Default false.
environment one of the twelve above Use that pretrained model. Needed with depth; with bams, exactly one BAM.
depth file coverm_contig’s metabat table with one sample (its header is checked: five columns).
bams list of files Coordinate-sorted BAMs (checked: SO:coordinate in the header; SemiBin2 runs bedtools genomecov on them).
tag text Bin file prefix, default SemiBin. Give each sample its own: galah and CoverM name genomes after the file.
min_len integer, at least 500 Shortest contig binned. Default: SemiBin2 picks 1000 or 2500 bp from the assembly (2500 for the sample below).
minfasta_kbs integer Smallest bin written, in kb (default 200).
seed integer Default 1 here; without a seed SemiBin2’s results may differ between runs.
threads integer SemiBin2’s default is every CPU.

The server always passes --compression=none (SemiBin2’s default is gzip; plain FASTA is what checkm2 with extension: fa and galah read here) and --engine=cpu (the same bins on a machine with a GPU). Returns each bin’s contigs, length, N50 and GC, the bin count and the binned length. SemiBinRun.log is volatile; recluster_bins_info.tsv names the output folder, so it only matches when replayed into the same path, as replay.sh does. Not offered: --semi-supervised (mmseqs2 and GTDB, over 100 GB), --abundance (strobealign-aemb files, which SemiBin2 only takes from five samples on), long-read mode, CRAM, --separator, and the training and graph settings.

Measured on 2026-11-14 on this project’s laptop (12 cores, 30 GB, shared: 1-minute load 8-29), each step under an 8 GB no-swap cap, 6 threads, on the Crystal Geyser sample of the MAG laptop test (its MEGAHIT contigs and CoverM depth table):

Run Wall Peak (cgroup) Bins Mb binned high* / medium / low (isotable MAG mode) Bins with contamination ≥ 10%
MetaBAT2 (earlier run, same contigs and depth) 2.6 s 0.24 GiB 23 24.4 4 / 13 / 6 1
SemiBin2 global, depth 74-109 s (54 s through irit-mcp) 1.11-1.48 GiB 25 26.7 4 / 11 / 10 2
SemiBin2 ocean, depth 59 s 0.88 GiB 26 26.3 3 / 13 / 10 2
SemiBin2 soil, depth 54 s 0.85 GiB 27 26.8 3 / 12 / 12 2
SemiBin2 trained on the sample, one BAM killed after 244 s and 398 s 8 GB cap
  • On this CPR-rich groundwater sample the pretrained models gave 2-4 more bins than MetaBAT2 and 2-2.4 Mb more binned sequence, but not better bins: 15-16 of them were at least 50% complete with under 10% contamination, against MetaBAT2’s 17. No model was trained on groundwater. Other data may differ; this is one sample.
  • Two runs of global with seed 1 gave byte-identical bins (recluster_bins_info.tsv differed only by the output folder it names), and so did the call through irit-mcp (other tag).
  • Self-supervised training does not fit in 8 GB. It was killed at the cap twice, in its first training epoch (about 3 minutes each, of 15). SemiBin2 2.6.0 builds min(500 × contigs, 4 million) random contig pairs as feature rows every epoch (train_self in self_supervised_model.py), about 2.2 million pairs for the 4,455 split contigs here; the batch size doesn’t change that. A call without environment therefore carries a warning before it runs, and a SemiBin2 killed in training gets a hint to use a pretrained environment. On 32 GB or more it should run.
  • CheckM2 (lowmem) on the 25-27 bins: 356-461 s, 3.5-4.4 GiB.

Multi-sample binning: semibin2_concatenate and multi

Section titled “Multi-sample binning: semibin2_concatenate and multi”

SemiBin2’s multi-sample mode bins each sample’s own assembly, but with the coverage of every sample as features, which separates genomes that one sample’s coverage can’t. Three calls:

  1. semibin2_concatenate (SemiBin2 concatenate_fasta) joins the samples’ contigs into <outdir>/concatenated.fa, each contig renamed <sample>:<contig>. SemiBin2 takes the sample name from the file name up to its first dot, and every MEGAHIT assembly is final.contigs.fa, so the server links each file as <outdir>/inputs/<sample>.fa (recorded, and made again by replay.sh) under the name given in samples.
  2. coverm_contig with concatenated.fa as reference, every sample’s reads and bam_cache_dir: one BAM per sample, all against the same contigs.
  3. semibin2 with multi: true, contigs the concatenated file and bams those BAMs (SemiBin2 multi_easy_bin). It trains a model for each sample in turn (self-supervised; there are no pretrained models for this mode) and bins each sample’s contigs with it.
{"name": "semibin2_concatenate", "arguments": {"contigs": ["asm/s1/final.contigs.fa", "asm/s2/final.contigs.fa",
"asm/s3/final.contigs.fa"], "samples": ["s1", "s2", "s3"], "outdir": "multi/concat"}}
{"name": "coverm_contig", "arguments": {"reference": "multi/concat/concatenated.fa",
"r1": ["trim/s1_1.fastq.gz", "trim/s2_1.fastq.gz", "trim/s3_1.fastq.gz"],
"r2": ["trim/s1_2.fastq.gz", "trim/s2_2.fastq.gz", "trim/s3_2.fastq.gz"],
"output": "multi/mean.tsv", "bam_cache_dir": "multi/bams", "threads": 6}}
{"name": "semibin2", "arguments": {"contigs": "multi/concat/concatenated.fa", "multi": true, "outdir": "multi/sb",
"bams": ["multi/bams/concatenated.fa.s1_1.fastq.gz.bam", "multi/bams/concatenated.fa.s2_1.fastq.gz.bam",
"multi/bams/concatenated.fa.s3_1.fastq.gz.bam"], "threads": 6}}
{"name": "checkm2", "arguments": {"genome_dir": "multi/sb/bins", "extension": "fa", "outdir": "checkm2", "lowmem": true}}
Parameter (semibin2_concatenate) Type Meaning
contigs list of files (required) Each sample’s assembly, FASTA (plain or gzip); two or more, each file once.
samples list of names (required) One per file, same order: letters, digits, _, - (no dot, which SemiBin2 cuts at, nor :, its separator).
outdir folder (required) Output folder; one with files needs overwrite.
min_len integer Leave out shorter contigs (--min-len). Default: none left out.

semibin2 with multi checks that every contig name has a sample in front and that each sample’s contigs are together (as semibin2_concatenate writes them), and refuses environment, depth and fewer than two BAMs; it warns when the BAMs and samples differ in number. Bins are written per sample to <outdir>/samples/<sample>/output_bins/<tag>_<n>.fa, and SemiBin2 copies all of them to <outdir>/bins/<sample>_<tag>_<n>.fa: run checkm2 and galah on that one folder (the sample in each name keeps them apart), and isotable mode mag on the CheckM2 report. The result lists each bin with its sample. SemiBinRun.log of both tools is volatile; the bins, features (samples/<sample>/data.csv) and models (model.pt) were byte-identical between two runs with seed 1 (on the two-genome mock below), and recluster_bins_info.tsv names the output folder, as in single-sample mode.

Measured on 2026-11-15 on this project’s laptop (12 cores, 30 GB, shared: 1-minute load 3-25), each step under an 8 GB no-swap cap, 6 threads, on three filtrate samples of one site: the Crystal Geyser time series, BioProject PRJNA297582 (SRR2638367, SRR2638368, SRR2638369: “filtrate 05”, “06” and “07”). Each run was read from ENA with its MD5 checked and cut to 0.5 Gb with rasusa (seed 1): 3.49-3.51 million reads per sample. ENA serves these runs as unpaired reads (every read /1), and coverm_contig then took pairs only, so CoverM 0.8.0 was run by hand with --single for the depths and BAMs (the same contig subcommand, methods and BAM cache); everything else went through irit-mcp. coverm_contig has taken single since.

Step Wall Peak (cgroup) Result
megahit (single), per sample 13-19 min 1.2-1.3 GiB 24.3-28.5 Mb, N50 851-1,106 bp; 544-718 contigs of 4 kb or more
semibin2_concatenate 0.9 s 0.09 GiB 101,916 contigs
CoverM, the three samples to concatenated.fa, BAMs kept 152 s 2.59 GiB 71-73% of reads mapped; BAMs of 304-314 MB
semibin2 multi 48 min (training 13-18 min per sample) 4.33 GiB 14 bins, 19.6 Mb
checkm2 lowmem, the 50 bins below 458 s 5.47 GiB

The same three assemblies binned four ways, graded by isotable mode mag on one CheckM2 report:

Binning Wall Bins Mb binned high* / medium / low ≥ 50% complete, < 10% contamination Contamination ≥ 10%
MetaBAT2, the sample’s own depth under 1 s per sample 11 18.7 4 / 5 / 2 9 1
MetaBAT2, depth of all three samples under 1 s per sample 11 21.0 5 / 4 / 2 9 0
SemiBin2 global, the sample’s own depth 17-21 s per sample 14 20.3 5 / 5 / 4 10 0
SemiBin2 multi 48 min for the three 14 19.6 5 / 5 / 4 10 0
  • Multi-sample binning fitted in 8 GB here, at 4.3 GiB. Its training holds 1,000 random contig pairs per contig of 4 kb or more as feature rows each epoch (train_self; such contigs are split in two for must-link pairs), so the peak follows the sample with the most of them: 718 here (718,000 pairs). Single-sample training of the deeper sample above (about 2,200 such contigs, 2.2 million pairs) was killed at the cap; where between the two the limit lies was not measured. A multi call carries a warning with these numbers before it runs.
  • Training is the slow part: 13-18 minutes per sample at 15 epochs, against about 20 seconds per sample for a pretrained model. The epochs and batch size don’t change the peak (the pair arrays are built whole each epoch); --ml-threshold would (fewer contigs split, fewer pairs), but wasn’t needed here, so the training settings are still not offered.
  • On these samples it binned no better than the pretrained global model: the same bin count and tiers, and nearly the same bins: 13 of the 14 had 93-100% of their length in one global bin of the same sample. These are three filtrates of one site, at 0.5 Gb each; other data may differ. Giving MetaBAT2 all three samples’ depth removed its one contaminated bin.
  • On the two-genome mock of the real-tools workflow (the SKESA assembly of the S. aureus reads and a MEGAHIT assembly of the M. genitalium pairs), semibin2 multi took 179-201 s at 0.74-0.79 GiB and put each genome in one bin (2.77 and 0.57 Mb); two runs gave byte-identical bins, features and models. The workflow runs this route. The real run above was not repeated.

Dereplicates genomes, typically the bins of several samples, with galah (galah cluster): genomes within an ANI (default 95%, a species) and aligned fraction of each other form a cluster, and one genome represents it. skani does the comparisons. Writes <outdir>/clusters.tsv (representative<TAB>member lines, paths as given) and <outdir>/representatives.txt, one path per line, which coverm_abundance takes as genome_list. No copies are made: galah refuses a copy folder that has files, which a replay in the same folder would hit.

Parameter Type Meaning
genomes list of files Genome FASTA files.
genome_dirs list of folders Folders of genomes, matched by extension (default fa, MetaBAT2’s and SemiBin2’s). Give this and/or genomes.
outdir folder (required) Where clusters.tsv and representatives.txt go; an existing one needs overwrite.
ani percent, 80-100 Default 95.
min_aligned_fraction percent galah’s default 15.
precluster_ani percent, at most ani galah’s default 90.
checkm2_report file A CheckM2 quality_report.tsv listing every genome. Each cluster’s best genome by quality_formula represents it; without a report, the first genome given does (and a warning says so).
min_completeness, max_contamination percent Leave genomes out by CheckM2’s numbers (need checkm2_report).
quality_formula Parks2020_reduced (galah’s default), completeness-4contamination, completeness-5contamination How the representative is chosen. galah’s dRep formula is not offered: it needs CheckM 1’s strain heterogeneity.
small_genomes boolean skani’s settings for genomes under about 20 kb.
threads integer Default 1 here (below).

Checks before running: genomes are named after their files (without the FASTA extension), as galah, CheckM2 and CoverM name them, so two files with one name (bin.1.fa of two samples) are refused: give each sample’s bins their own prefix (metabat2 prefix, semibin2 tag). galah takes one --checkm2-quality-report and panics when a genome is missing from it (“Failed to find CheckM statistics”), so the server checks that every genome has a row and refuses the call otherwise: run checkm2 once over all the genomes (its genomes list).

Returns the clusters (sorted, with their members and sizes), the number of genomes given and of clusters, and the genomes left out by the quality filters. With more than one thread galah 0.6.3 writes clusters.tsv and representatives.txt in a different order each run (the same clusters: checked on 48 bins, sorted files identical); with one they were byte-identical. One thread is the default, and with more both files are volatile. One thread was fast enough: 48 bins in 0.84 s.

Install: Bioconda’s galah=0.6.3 also installs CheckM2 with TensorFlow (about 1 GB) for --run-checkm2, which irit-mcp doesn’t use. galah itself only needs skani on PATH: micromamba create -n galah -c conda-forge -c bioconda skani=0.4.0, then micromamba install -n galah --no-deps -c conda-forge -c bioconda galah=0.6.3 (1 MB). Not offered: --run-checkm2, CheckM 1 and dRep quality tables, FastANI and finch, contig clustering, --reference-genomes, --low-memory.

Measured (2026-11-14, same laptop and cap): the 23 MetaBAT2 bins and the 25 SemiBin2 global bins of the Crystal Geyser sample, with one CheckM2 report for all 48 (the two reports joined by hand), in 0.84 s and 84 MB: 24 clusters, 22 of them a MetaBAT2 bin and a SemiBin2 bin of the same genome, one of three and one single SemiBin2 bin. 12 representatives came from each binner.

Each genome’s abundance in each sample: maps every sample’s reads to a set of genomes (coverm genome with --genome-fasta-files, all genomes in one reference) and writes one table, a row per genome plus unmapped, and per sample <read 1 file> Relative Abundance (%), Mean, Covered Fraction and Read Count columns (CoverM’s dense layout). This is the genome × sample table a co-occurrence analysis across samples takes.

Parameter Type Meaning
genome_list file A list of genome paths, one per line: galah’s <outdir>/representatives.txt. Read again on replay, so the genomes follow a re-run galah.
genomes, genome_dirs, extension as for galah Instead of genome_list: genome files, or folders of them. One folder alone is passed to CoverM as a folder (-d), so a replay takes whatever it then holds. Names must be unique.
r1, r2 lists of files (required) One read pair per sample. Columns are named after the read 1 file, so name the files after the samples; two read 1 files with one name are refused.
output file (required) The table (TSV).
min_covered_fraction percent: 0, or 1-100 Default 0 here (CoverM’s own is 10).
mapper, min_read_percent_identity, min_read_aligned_percent, threads As for coverm_contig.
overwrite boolean Default false.

Why a separate tool from coverm_genome: that one is for an isolate (one assembly, one genome, --single-genome, isotable’s naming and the Shovill depth check); this one is many genomes and many samples, for MAGs.

What the numbers mean (cited, the CoverM paper, Equation 1, and its README): a genome’s relative abundance is its share of the summed mean coverage of all the genomes given, times the fraction of the sample’s reads that aligned to any of them, so it estimates the share of cells and is a share of all reads; the unmapped row holds “the reads that did not map to any of the provided genomes”. Two things follow, which is why the genomes should be one dereplicated set given in one call: abundances are only comparable across samples when every sample was mapped to the same set, and a genome left out leaves its reads unmapped or on its relatives.

min_covered_fraction: CoverM reports a genome covered less than this as 0 in that sample, and CoverM 0.8.0 refuses the count method unless it is 0 (“does not calculate the covered fraction”). So the default is 0, and the table’s Covered Fraction column lets a later step set its own presence threshold. With a value above 0 the table has no Read Count columns (a warning says so). Values between 0 and 1 are refused: CoverM would read them as fractions.

Returns, per sample, the reads mapped and their percentage (from CoverM’s log), the unmapped percentage and how many genomes have an abundance above 0; and the genome count and the columns per sample. Not offered: --dereplicate (galah is its own recorded step), sharding, BAM input, sparse output.

Measured (2026-11-14, same laptop and cap, 6 threads): the 24 galah representatives above, with the Crystal Geyser sample’s trimmed reads split into two halves of 2.43 million pairs as two “samples”: 91 s, 1.90 GiB. 41.5% and 41.7% of the reads mapped (73.3% map to the whole assembly); all 24 genomes were detected in both halves. A two-sample stand-in test checks the table’s layout; this real run checks the layout and the time and memory, not biology (both halves are one sample).

Example: several samples to a genome × sample table

Section titled “Example: several samples to a genome × sample table”
{"name": "coverm_contig", "arguments": {"reference": "asm/s1/final.contigs.fa", "r1": ["trim/s1_1.fastq.gz"],
"r2": ["trim/s1_2.fastq.gz"], "output": "depth/s1.depth.tsv", "methods": ["metabat"], "threads": 6}}
{"name": "semibin2", "arguments": {"contigs": "asm/s1/final.contigs.fa", "depth": "depth/s1.depth.tsv",
"environment": "global", "outdir": "bins/s1", "tag": "s1", "threads": 6}}
... the same for s2, s3, ... (or metabat2 with prefix s2, ...)
{"name": "checkm2", "arguments": {"genomes": ["bins/s1/output_bins/s1_0.fa", "..."], "outdir": "checkm2", "lowmem": true}}
{"name": "galah", "arguments": {"genome_dirs": ["bins/s1/output_bins", "bins/s2/output_bins"],
"checkm2_report": "checkm2/quality_report.tsv", "min_completeness": 50, "max_contamination": 10, "outdir": "derep"}}
{"name": "coverm_abundance", "arguments": {"genome_list": "derep/representatives.txt",
"r1": ["trim/s1_1.fastq.gz", "trim/s2_1.fastq.gz"], "r2": ["trim/s1_2.fastq.gz", "trim/s2_2.fastq.gz"],
"output": "abundance.tsv", "threads": 6}}

CheckM2 over many bins in one call needs memory (48 genomes peaked at 7.7 GiB, above); galah takes one report, so for more bins than fit, join the batches’ quality_report.tsv files under one header line (outside irit-mcp, for now).

Example: an isolate from reads to resistance genes

Section titled “Example: an isolate from reads to resistance genes”

A session an agent might run (paths shortened):

{"name": "fastp", "arguments": {"in1": "reads/s1_R1.fastq.gz", "in2": "reads/s1_R2.fastq.gz",
"out1": "trim/s1_R1.fastq.gz", "out2": "trim/s1_R2.fastq.gz", "json": "trim/s1.fastp.json"}}
{"name": "shovill", "arguments": {"r1": "trim/s1_R1.fastq.gz", "r2": "trim/s1_R2.fastq.gz",
"outdir": "asm/s1", "assembler": "skesa", "ram": 8, "link_as": "genomes/s1.fna"}}
{"name": "dblock_env", "arguments": {}}
{"name": "bakta", "arguments": {"genome": "asm/s1/contigs.fa", "prefix": "s1", "outdir": "bakta/s1", "skip": ["plot"]}}
{"name": "checkm2", "arguments": {"genomes": ["genomes/s1.fna"], "outdir": "checkm2", "lowmem": true}}
{"name": "gtdbprep_ani", "arguments": {"genome_dir": "genomes", "index": "/db/ani-screen-r232", "work": "ani", "species_only": true}}
{"name": "gtdbtk_classify_wf", "arguments": {"genome_dir": "genomes", "data_path": "ani/gtdbtk_data", "out_dir": "gtdbtk", "pplacer_cpus": 1}}
{"name": "mlst", "arguments": {"contigs": ["asm/s1/contigs.fa"], "outfile": "typing/s1.mlst.tsv"}}
{"name": "amrfinder", "arguments": {"nucleotide": "asm/s1/contigs.fa", "organism": "Staphylococcus_aureus",
"plus": true, "output": "typing/s1.amrfinder.tsv"}}
{"name": "isotable", "arguments": {"dirs": ["trim", "asm", "checkm2", "gtdbtk", "typing"]}}

None of the folders (trim/, asm/, genomes/, …) need to exist first. CheckM2 and GTDB-Tk name genomes after the file, so Shovill’s link_as makes genomes/s1.fna a link to asm/s1/contigs.fa: the genome is s1 in their results and isotable joins it. isotable’s default isolate requirements (reads, Q30, contigs, N50, completeness) are then all met.

The run’s replay.sh then has lines like these:

want_ext_version fastp 'fastp 1.4.0'
want_ext_version gtdbtk 'gtdbtk: version 2.8.0 Copyright 2017 Pierre-Alain Chaumeil, ...'
# call 001: fastp (ok, 2026-11-10T09:12:03.120Z)
cd /data/demo || exit 1
step 001 0 ext fastp --in1=reads/s1_R1.fastq.gz --in2=reads/s1_R2.fastq.gz ...
# call 005: gtdbtk_classify_wf (ok, 2026-11-10T09:58:40.002Z)
cd /data/demo || exit 1
GTDBTK_DATA_PATH=/home/u/.local/share/dblock/gtdbtk-r232/release232; export GTDBTK_DATA_PATH
step 005 0 ext gtdbtk classify_wf --genome_dir=asm --out_dir=gtdbtk --pplacer_cpus=1 --scratch_dir=scratch
{"name": "fastp", "arguments": {"in1": "reads/m1_1.fastq.gz", "in2": "reads/m1_2.fastq.gz",
"out1": "trim/m1_1.fastq.gz", "out2": "trim/m1_2.fastq.gz", "json": "trim/m1.fastp.json"}}
{"name": "megahit", "arguments": {"r1": ["trim/m1_1.fastq.gz"], "r2": ["trim/m1_2.fastq.gz"],
"outdir": "asm/m1", "memory_gb": 6, "threads": 6}}
{"name": "coverm_contig", "arguments": {"reference": "asm/m1/final.contigs.fa", "r1": ["trim/m1_1.fastq.gz"],
"r2": ["trim/m1_2.fastq.gz"], "output": "depth/m1.depth.tsv", "methods": ["metabat"], "threads": 6}}
{"name": "metabat2", "arguments": {"contigs": "asm/m1/final.contigs.fa", "depth": "depth/m1.depth.tsv",
"outdir": "bins/m1", "threads": 6}}
{"name": "checkm2", "arguments": {"genome_dir": "bins/m1", "extension": "fa", "outdir": "checkm2", "lowmem": true, "threads": 6}}
{"name": "gtdbprep_ani", "arguments": {"genome_dir": "bins/m1", "extension": "fa", "work": "ani", "species_only": true}}
{"name": "gtdbtk_classify_wf", "arguments": {"genome_dir": "bins/m1", "extension": "fa", "data_path": "ani/gtdbtk_data",
"out_dir": "gtdbtk", "pplacer_cpus": 1}}
{"name": "isotable", "arguments": {"dirs": ["checkm2", "gtdbtk"], "mode": "mag"}}

isotable’s MAG mode gives each bin a MIMAG tier from CheckM2’s completeness and contamination. Use CheckM2’s lowmem for more than a few bins under 8 GB: at its default DIAMOND block size it was killed at an 8 GB cap on 23 MAGs, and with lowmem it peaked at 5.6 GiB. The laptop test ran this on a groundwater metagenome inside 8 GB.

describe_run (run_id, default the current run) returns the paths of replay.sh and the RO-Crate and a summary of each call: tool, status, version, exit status, error, warnings and output paths. detail: true returns every call’s full record instead (command, environment, every input and output with SHA-256), which can be tens of kB per call; call_id returns one call in full. list_runs lists the runs in the runs folder with call counts.

Every tool result carries call_id and run_id. Failures have isError: true and an error field:

error Meaning
invalid_parameter Refused before running; field and message say why. Recorded, not replayed.
tool_failed The tool ran and exited non-zero; exit_status, stderr, stdout. Its outputs must not be used.
tool_unavailable The binary was not found or could not start.
no_reports leanqc exited 0 but wrote no report; there is no QC result.
missing_outputs A third-party tool exited 0 but didn’t write the files it always writes; message lists them. Recorded as failed.
output_unreadable sheetgen, isotable or a third-party tool exited 0 but its output could not be read back.

A parameter that isn’t in the schema is refused by the MCP layer itself, with the list of valid names.

One folder per server session, irit-runs/<run-id>/, rewritten after every call:

irit-runs/20261110T074754Z-41022/
run.json every call, in order
replay.sh re-runs the successful calls and checks the outputs
ro-crate-metadata.json the same, as a Workflow Run RO-Crate
calls/001.stdout each call's stdout and stderr
calls/001.stderr

A call in run.json (from a real session, with paths shortened and lists trimmed):

{
"id": 2,
"mcp_tool": "leanqc",
"status": "ok",
"params": {"files": ["reads/s1_R1.fastq", "reads/s1_R2.fastq"], "outdir": "qc", "no_html": true},
"program": "/opt/irit/bin/leanqc",
"argv": ["leanqc", "--outdir=qc", "--no-html", "--", "reads/s1_R1.fastq", "reads/s1_R2.fastq"],
"version": "leanqc 0.1.0",
"cwd": "/data/demo",
"started": "2026-11-10T07:47:54.881Z",
"ended": "2026-11-10T07:47:54.900Z",
"exit_status": 0,
"inputs": [
{"path": "/data/demo/reads/s1_R1.fastq", "size": 21890, "sha256": "0d434ae6..."}
],
"outputs": [
{"path": "/data/demo/qc/s1_R1_leanqc.json", "size": 12991, "sha256": "fbc19cfa..."}
],
"stdout": "calls/002.stdout",
"stderr": "calls/002.stderr",
"env": {"DBLOCK_STORE": "/home/u/.local/share/dblock"}
}

version is the first line the tool printed for --version; it is left out when --version failed or printed nothing. Third-party calls also have "external": true.

status is ok, failed (non-zero exit), rejected (invalid parameters, with error) or error (binary missing). Inputs are the files the call reads; a folder input (sheetgen, isotable) is listed file by file. Outputs are the files under the call’s output paths that are new or changed after it ran. “Changed” compares size, modification time, inode number and inode change time (on Unix), and the SHA-256 of files under 1 MB, so a rewrite with the same size inside the same timestamp tick is still seen. An output path that is itself a symlink (qc -> /scratch/qc) is followed; symlinks inside it (sheetgen’s link_into) are recorded with symlink_to.

Calls whose output paths overlap (the same path, or one inside the other) run one after the other, so each call’s outputs are only its own; other calls run in parallel.

env holds the environment that decided where the tool looked or wrote, as the resolved value the server computed with the tool’s own rules. The server passes exactly these values to the tool, so the record and the run agree, and replay.sh exports them before the call:

Tool Recorded Resolved from
dblock_* (except catalog) DBLOCK_STORE $DBLOCK_STORE, else $XDG_DATA_HOME/dblock, else $HOME/.local/share/dblock
sheetgen with pipeline NXF_HOME $NXF_HOME, else $HOME/.nextflow
gtdbtk_classify_wf GTDBTK_DATA_PATH data_path, else $GTDBTK_DATA_PATH, else the one locked in ./dblock.lock

Bakta, CheckM2 and AMRFinderPlus get their database as a flag (--db, --database_path, --database), resolved the same way from BAKTA_DB, CHECKM2DB and AMRFINDER_DB, so it is in argv.

With pipeline, the schema_input.json sheetgen will use (same lookup as sheetgen: the assets/<name> checkout, else the newest clone) is also hashed into inputs.

Not captured: PATH and other variables, locale, the user, the machine; a store = line in dblock.toml (it wins over DBLOCK_STORE, and dblock.toml is hashed as an input instead); ~/ in such a line, which dblock expands with the replaying user’s HOME; the contents of the dblock store and of the Nextflow cache beyond the one schema file.

Options are always written as --name=value and positional arguments after --, so a file name starting with - can’t be read as a flag.

sh irit-runs/<run-id>/replay.sh # binaries from PATH
IRIT_BIN_DIR=/opt/irit/bin sh irit-runs/<run-id>/replay.sh # or from a folder

Third-party tools (fastp, shovill, flye, medaka_consensus, bakta, checkm2, gtdbtk, mlst, amrfinder, megahit, coverm, metabat2, kleborate, rasusa) are always taken from PATH, so activate their conda environment first. IRIT_BIN_DIR applies to the irit tools only.

Some third-party outputs differ between two identical runs. They are recorded with "volatile": true and their hash, and replay.sh only checks that they exist (check_exists). Every other output is checked by hash. The lists come from running each tool twice with the same inputs and paths in the real-tools workflow (below) and comparing every file:

Tool Volatile outputs Why they differ
fastp .html The HTML report; the JSON report is identical.
shovill everything shovill.log has times and the machine’s CPUs and RAM; every contigs.fa header carries the date, so it differs on another day. SPAdes 3.15.5 gave different contigs in two identical runs (2,803,881 bp both times, same ST). SKESA’s were identical in the real-tools workflow, but SKESA 2.5.1 with 8 CPUs gave 57 contigs once and 56 twice from identical reads in the laptop run.
gtdbprep ani .log, .gz Logs; the gzip header of GTDB-Tk’s unassigned-hits file carries a time.
mlst .json Same values, keys in another order (mlst writes it without sorting, and Perl randomises hash order). The TSV is identical.
bakta .log, .gbff, .embl, .json, .svg Run times and dates (GenBank LOCUS date; in the JSON only run.start and run.end).
checkm2 checkm2.log Timestamps.
gtdbtk .log, gtdbtk.json, .gz Timestamps (in gtdbtk.json only each step’s start and end); gzip headers carry a time.
megahit everything The log has times; final.contigs.fa differed between two identical runs in the real-tools workflow (same 92 contigs, 3,384,504 bp and N50 both times), and so did the intermediate contigs. Replay compares the assembly’s contig count, length and N50, as for Shovill.
coverm_contig none Three runs on the same assembly and reads gave identical depth tables (MAG laptop test); it differs on replay only when the assembly it reads did.
coverm_genome none Byte-identical table on replay on the laptop (BfR-EC-20867, 4 threads).
kleborate none Byte-identical tables on replay on the laptop (BfR-EC-20867). Not yet checked by the real-tools workflow.
metabat2 none With the seed irit-mcp passes (1 unless set), a second run gave identical bins and bin.BinMembers.txt; bin.BinInfo.txt names the output folder. MetaBAT2’s own default seed is random.

The script warns when a tool’s --version (its first line) differs from the recorded one (a tool whose version couldn’t be read in the run gets one “version unknown” line instead), exports each call’s recorded env, re-runs each successful call in its original folder (stdout and stderr go to replay/NNN.* beside the script), then checks the SHA-256 of every output (the last version, if several calls wrote the same file), and of stdout where stdout is the result (a sheet or table not written to a file, dblock catalog, dblock env). It exits 0 only if every command exits as it did and every hash matches, apart from the outputs that follow a changed input (below). Failed and rejected calls appear as comments.

Outputs made from a volatile output. A volatile output can feed later calls: CheckM2 and GTDB-Tk read Shovill’s assembly, isotable reads CheckM2’s report. If the replayed assembly is a different one, those outputs differ too, and that is not a fault of theirs. So before re-running a call, replay.sh checks every input of it that an earlier call of the run wrote (check_in). If one differs from what the call read in the run, the call’s outputs are checked with check_from: a different one is printed as differs, made by call NNN from an input that differs and counted, but does not fail the replay. A missing one is treated the same way (missing, made by call NNN ...): a binner given other contigs can make other bins, and SemiBin2 numbers its bins by cluster, so the run’s sb_1.fa may not exist after a replay. An output that is missing, or that differs, although every input it was made from matched, still fails the replay. The last line then says how many outputs matched and how many differ only because of such an input. For an assembly, replay.sh also prints its contig count, length and N50 against the run’s (assembly_note), e.g.

replay: call 009: assembly /data/b168/asm/b168/contigs.fa is now 56 contigs, 4151999 bp, N50 185951; the run had 57 contigs, 4152275 bp, N50 185951
replay: call 013 reads /data/b168/genomes/b168.fna, which differs from the run
replay: differs, made by call 013 from an input that differs: /data/b168/checkm2/quality_report.tsv
replay: 12 commands re-run, 27 of 31 outputs match; 4 differ only because a file they were made from differs (see above)

A successful dblock_fetch is not repeated by default, since it would download the databases again: the script prints that it skipped it, the exact command is in a comment, and the check of the dblock.lock it wrote is skipped too. Run with IRIT_REPLAY_FETCH=1 to fetch again:

IRIT_REPLAY_FETCH=1 sh irit-runs/<run-id>/replay.sh

Everything taken from a call (arguments, paths, versions, env values) is single-quoted, and every comment line is written through one helper that escapes newlines, carriage returns and other control characters, so a value can’t end a comment and start a command. The server also refuses control characters in every path and text parameter, so they never reach a tool’s argv. An excerpt:

want_version leanqc 'leanqc 0.1.0'
# call 002: leanqc (ok, 2026-11-10T07:47:54.881Z)
cd /data/demo || exit 1
step 002 0 irit leanqc --outdir=qc --no-html -- reads/s1_R1.fastq reads/s1_R2.fastq
# call 005: leanqc (rejected, 2026-11-10T07:47:54.946Z)
# not run: phred: 40 is not 33 or 64
# outputs
check fbc19cfa4e3a31daabbaec0ffda5e39ae9614937132f8f9e7cabfcdfc8d7a735 /data/demo/qc/s1_R1_leanqc.json

ro-crate-metadata.json follows the Process Run Crate profile 0.6 (RO-Crate 1.3): one CreateAction per call that ran, with the tool as a SoftwareApplication (softwareVersion), inputs as object, outputs as result, start and end times, and FailedActionStatus for failed calls. The root Dataset has a description and a license (CC0 1.0, for the run record itself; the data files keep their own terms). run.json, replay.sh and every calls/NNN.stdout / .stderr are listed in hasPart. The data files are not copied in; they are referenced by file:// URI, so the crate describes the run but does not carry the data.

  • No shell. The binaries are started with an argument vector; nothing passes through a shell. replay.sh single-quotes every value and escapes comments (see Replaying); control characters are refused in parameters.
  • Writes stay in the root and don’t replace existing files without overwrite: true (see Where tools may write).
  • Downloads need confirmation. dblock_fetch refuses unless confirm: true, and its description tells the agent to show the user dblock_plan first. dblock itself still refuses databases that won’t fit on disk.
  • No deleting tools. dblock remove is not exposed.
  • Stdin is closed for every tool, so nothing can wait for input.
  • Unit tests: parameter checks and argument vectors for every tool (missing paths, bad enums, out-of-range numbers, schema with pipeline, unconfirmed fetch, unsafe database ids, unknown parameters, control characters, writes outside the root through .., absolute paths and symlinks, overwriting), resolved environment, shell quoting, replay.sh generation, output detection (symlinked output folders, same-size rewrites), serialising overlapping calls, run.json and RO-Crate writing, and parsing of the tables and dblock output.
  • A replay.sh built from hostile values (newlines, carriage returns, quotes, $(...), backticks, leading dashes) in every field it is generated from passes sh -n, and running it with stub tools creates nothing but its own replay/ folder.
  • An integration test starts irit-mcp over stdio, speaks raw JSON-RPC (initialize, tools/list, tools/call), runs leanqc on a generated FASTQ pair, checks the run record against the files on disk, deletes the reports, runs replay.sh and gets the same SHA-256 for every output. It then changes an input and checks that replay.sh fails and names the file that differs. A second one replays the review’s cases: leanqc into a symlinked outdir, a second leanqc refused without overwrite, sheetgen refused for a file outside the root and for a newline in set, and the replay of that session. No network.
  • Third-party tools: unit tests map parameters to argv for each tool and check the refusals (wrong file type, gzip and empty inputs, contradictory flags, out-of-range values, database folders missing a file or of the wrong version, GTDB-Tk data without skani/, flags that don’t exist in the pinned version such as skip_ani_screen and max_memory). An integration test (Unix only) puts shell-script stand-ins for fastp, bakta, checkm2 and gtdbtk on PATH. Each stand-in refuses any flag the wrapper isn’t allowed to send. The test runs the isolate path over stdio, checks the summaries, a failed run, an exit 0 without outputs, a version warning and the run record, then deletes the outputs, replays and gets the same hashes. A second test checks the install hint when a tool is missing. A third runs stand-ins for shovill, mlst and amrfinder (with a stand-in indexed database from $AMRFINDER_DB), then the real isotable binary, and checks that the mlst row (labelled from s1.mlst.tsv) and the AMRFinderPlus report join to sample s1 although the assembly is contigs.fa, then replays. A fourth uses a Shovill stand-in whose assembly changes every run and a CheckM2 stand-in whose report holds the genome’s size: after deleting every output folder, replay.sh succeeds, prints the new assembly’s contigs, length and N50 beside the run’s, and reports CheckM2’s report and isotable’s row as following it, while fastp’s JSON still matches; a fastp JSON changed by hand still fails the replay.
  • With the real programs: the opt-in workflow mcp-real-tools.yml installs fastp 1.4.0, Bakta 1.12.2, CheckM2 1.1.0 and GTDB-Tk 2.8.0 from Bioconda (one environment each), fetches the Bakta light and CheckM2 databases through dblock_add and dblock_fetch, and runs the four tools through irit-mcp on Mycoplasma genitalium G37 (reads simulated from it for fastp) and on GTDB’s mock database and test genome for GTDB-Tk. It runs each tool twice to find the volatile outputs, deletes the outputs and runs replay.sh. It only runs by hand: gh workflow run mcp-real-tools.yml. First result (2026-11-10): all calls succeeded; fastp 40,000 reads, Bakta 522 CDSs / 36 tRNAs / 3 rRNAs, CheckM2 98.9% complete and 0.08% contaminated, GTDB-Tk classified the mock test genome with ANI 100. replay.sh then re-ran 11 commands and all 41 outputs matched (run). Since then it also installs Shovill 1.4.2, mlst 2.35.0 and AMRFinderPlus 4.2.7, fetches amrfinderplus-db-4.2-2026-10-29.1 with dblock_fetch (dblock runs amrfinder_index), and runs fastp → Shovill (SKESA, 30x, no Pilon) → mlst → AMRFinderPlus on real Illumina reads of S. aureus ERR044595 (nf-core/bacass’s 1M-pair test files), AMRFinderPlus on Bakta’s proteins and GFF3 for M. genitalium, and Bakta with the dblock AMRFinderPlus database as its amrfinderplus-db/latest (a folder of links, no amrfinder_update). Results (2026-11-11): Shovill 2,760,249 bp in under 3 minutes; mlst saureus ST22 (EMRSA-15’s type); AMRFinderPlus mecA, mecR1, blaZ, blaI, tet(38), mepA, and the point mutations gyrA_S84L, parC_S80F, dfrB_A135T; isotable joined fastp, mlst and AMRFinderPlus into one passing row for sa; Bakta’s own AMRFinderPlus step ran on the dblock database; dblock_verify found every database folder unchanged afterwards. Shovill’s and AMRFinderPlus’s outputs were identical between the two runs (except shovill.log), though SKESA is not always so (see the volatile table); mlst’s JSON was not. GTDB’s mock database now comes through dblock_fetch too (gtdbtk-r232-mockup, since GTDB fixed its MD5). replay.sh re-ran 22 commands and all 53 outputs matched (run). Added on 2026-11-12: Shovill with SPAdes 3.15.5 and its default read correction, stitching and Pilon (30x) gave 2,803,881 bp in 77 s and mlst ST22 again, but a different contigs.fa in the second identical run (hence volatile); mlst’s record held 177 inputs (the assembly, VERSION.txt 2025-12-29, the scheme map, 12 BLAST files and 162 profile tables), found through mlst --help behind the workflow’s wrapper script; dblock_verify with deep re-hashed every file of the four databases, including the 162 of the AMRFinderPlus folder with dblock’s indexes, and all matched (run). The workflow now also runs coverm_genome on the S. aureus SKESA assembly, kleborate on K. pneumoniae HS11286’s RefSeq genome (expected: ST11, KPC-2) with M. genitalium as an assembly Kleborate gives no row, and assembly_stats on M. genitalium (one 580,076 bp contig); not yet run.
  • Stand-ins for the paper-redo gaps (2026-11-14): Shovill → assembly_stats (N50, L50, N90, L90 of a known assembly, and min_contig) → coverm_genome (Shovill logged 61×, mapping 20.5×: the warning) → kleborate through a wrapper script that execs it, with stand-in bundled data in lib/python3.12/site-packages (hashed into the record) → isotable with depth and kleborate required, then replay.
  • Stand-ins for several samples (2026-11-14): coverm_contig (depth for one sample, a cached BAM for the other) → semibin2 with a pretrained model and with the BAM → checkm2 over all bins → galah (refusing a report that misses genomes and two genomes with one name; run again over the same outdir) → coverm_abundance from galah’s list over two samples → replay from a clean folder. The stand-in BAM’s header changes every run, as CoverM’s does; the replay says the next call read a BAM that differs and still passes.
  • Stand-ins for multi-sample binning (2026-11-15): semibin2_concatenate (refusing a missing, repeated or dotted name and a file given twice) of two assemblies both called final.contigs.fa → coverm_contig of both samples to the concatenated contigs with bam_cache_dir → semibin2 multi (refusing a file without sample names, an environment and one BAM) → checkm2 and galah on its one bins folder → replay from a clean folder, the links remade.
  • With the real programs on the laptop (2026-11-15, 8 GB cap): the multi-sample route on the two-genome mock and on three Crystal Geyser samples, with MetaBAT2 and SemiBin2 global on the same assemblies, CheckM2 and isotable (numbers in Multi-sample binning). Not replayed (the run took about 2 hours); the stand-in test replays the route.
  • With the real programs on the laptop (2026-11-14, each step under an 8 GB cap, the Crystal Geyser sample): fastp → coverm_contig with bam_cache_dir (depth table identical to the earlier run’s) → semibin2 trained on the BAM (killed at the cap, twice) → galah → coverm_abundance → semibin2 global; then replay.sh from a folder without their outputs: “5 commands re-run, 62 outputs match”, 414 s, 4.46 GiB peak. Numbers in semibin2, galah and coverm_abundance. The real-tools workflow now also installs SemiBin2 and galah and runs coverm_contig with bam_cache_dir, semibin2 (trained, on the two-genome mock), galah over the MetaBAT2 and SemiBin2 bins and coverm_abundance; not yet run.
  • By hand: a session with sheetgen → leanqc → isotable → dblock_catalog replayed with all 7 outputs matching; dblock_add, plan, verify, env and check against a local project. On 2026-11-14, the real CoverM 0.8.0 and Kleborate 3.2.4 on BfR-EC-20867 from the paper redo: assembly_stats, coverm_genome, kleborate and isotable through irit-mcp, then replay.sh from a folder with their outputs deleted (“4 commands re-run, 5 outputs match”); and kleborate on HS11286 (ST11, KPC-2, QC warning ambiguous_bases) with M. genitalium (no row, and a warning naming it).
  • dblock_fetch has not been run through the server against the real servers (dblock’s own tests cover fetching).
  • An unknown parameter is refused by the MCP SDK before the server sees the call, so that refusal isn’t in the run record (refusals of known parameters are).
  • Inputs are hashed in full before each call, so a call on large FASTQ folders reads them twice.
  • replay.sh writes to the original paths; there is no option to replay into another folder.
  • The root check runs before the tool starts; a symlink swapped in between could still redirect a write (the server doesn’t sandbox the tools).
  • Calls with overlapping outputs wait for each other, but a call may still read files another call is writing.
  • The RO-Crate does not include the data, and has no agent (who ran it) yet.
  • No streamable HTTP transport.
  • The real programs are checked by the opt-in workflow on small genomes and GTDB’s mock database. With R232 data, GTDB-Tk has run through irit-mcp only on a laptop by hand, for a genome the ANI screen assigns (gtdbprep_ani, then data_path: <work>/gtdbtk_data; see the laptop run); tree placement through irit-mcp has not.
  • Bakta: the AMRFinderPlus data inside the Bakta v6 databases (amrfinderplus-db/) may be older than the amrfinder Bioconda installs with Bakta 1.12.2, and Bakta then fails with “amrfinder error”. Give Bakta dblock’s amrfinderplus-db-4.2-2026-10-29.1 as amrfinderplus-db/latest through a folder of links (dblock); running amrfinder_update into the dblock Bakta folder also works, but dblock_verify then reports that folder as changed.
  • Shovill 1.4.2 runs spades.py --version even when SKESA assembles; SPAdes 3.15.5’s script fails on the newest Python a Bioconda solve can pick, and Shovill then stops (“Can’t parse spades version”). Install it with python=3.11 (shovill=1.4.2 python=3.11), as the workflow does.
  • CheckM2 1.1.0 from Bioconda can fail to load TensorFlow on newer glibc (“cannot enable executable stack”). Setting GLIBC_TUNABLES=glibc.rtld.execstack=2 for CheckM2 works around it (the workflow does this in a wrapper script).
  • Kleborate from pip needs pandas and Kaptive 3.2.x besides what pip installs (see kleborate); Bioconda’s package works without that but downloads about 900 MB for ECTyper when installed.
  • assembly_stats has not been compared with a QUAST run (QUAST isn’t installed on the laptop); it follows QUAST 5’s basic_stats.py and matches hand counts and Kleborate’s contig statistics.
  • SemiBin2: single-sample self-supervised training did not fit in 8 GB on a real sample; the pretrained models and multi-sample binning of three 0.5 Gb samples did (see Multi-sample binning). Its training settings are not offered.
  • galah takes one CheckM2 report; bins checked in several CheckM2 batches need their reports joined by hand first.
  • A long Bakta or GTDB-Tk call blocks until it ends; there is no progress reporting or cancellation beyond the client closing the connection.