OpenParable
Skip to content
← Back to skills

Tbtools

Apps & Automation
tbtools

Tbtools is an Agent Skill for apps & automation published in the xuzhougeng/wispterm repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when the user asks about TBtools, TBtools-II, TBtools RPC API, TBtools CLI, or bioinformatics operations available through TBtools such as sequence manipulation, BLAST, GFF/GTF/GXF processing, expression tables, heatmaps, trees, MCScanX, DIAMOND, HMMER, MUSCLE, and IQ-TREE.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/xuzhougeng/wispterm/blob/HEAD/plugins/skills/tbtools/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tbtools, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

TBtools

Overview

TBtools-II is a Java-based bioinformatics toolkit that runs on Windows and macOS. Prefer TBtools' own bundled Java/RPC/CLI tools. Do not introduce Python, R, Conda, or other dependencies unless the user explicitly asks.

Honor TBTOOLS_HOME or TBTOOLS_JAR if set; fall back to the platform default.

Setup

Windows (PowerShell)

$TbtoolsHome = if ($env:TBTOOLS_HOME) { $env:TBTOOLS_HOME } else { "C:\Program Files\TBtools" }
$TbtoolsJar = if ($env:TBTOOLS_JAR) { $env:TBTOOLS_JAR } else { Join-Path $TbtoolsHome "TBtools_JRE1.6.jar" }
$env:Path = "$(Join-Path $TbtoolsHome 'bin');$env:Path"

Test-Path $TbtoolsJar
java -version

macOS / Linux (bash)

TBTOOLS_HOME="${TBTOOLS_HOME:-/Applications/TBtools-II}"
TBTOOLS_JAR="${TBTOOLS_JAR:-$(find "$TBTOOLS_HOME" -name 'TBtools*.jar' -maxdepth 4 2>/dev/null | head -1)}"
export PATH="$TBTOOLS_HOME/bin:$PATH"

[ -f "$TBTOOLS_JAR" ] && echo "jar: $TBTOOLS_JAR" || echo "TBtools jar not found — set TBTOOLS_JAR"
java -version

Use bin/ (bin\ on Windows) tools directly when the task is a standard external tool workflow:

blastn -query query.fa -db db_prefix -out results.tsv -outfmt 6
muscle -in input.fa -out aligned.fa
iqtree -s aligned.fa -m MFP -bb 1000 -nt AUTO
diamond blastp -d proteins.dmnd -q query.fa -o matches.tsv

RPC Server

Windows (PowerShell)

.\scripts\start_rpc_server.ps1 -Background

Direct form:

java -cp $TbtoolsJar biocjava.rpc.RpcServer

macOS / Linux (bash)

java -cp "$TBTOOLS_JAR" biocjava.rpc.RpcServer &

Default URLs:

PurposeURL
Health checkhttp://127.0.0.1:8765/health
JSON-RPChttp://127.0.0.1:8765/rpc

rpcPort is configurable in TBtools config. rpcBindAddress is normalized to loopback only (127.0.0.1 or ::1); do not expose the RPC server on 0.0.0.0.

RPC Helper

Windows (PowerShell)

function Invoke-TBtoolsRpc {
    param(
        [Parameter(Mandatory=$true)][string]$Method,
        [hashtable]$Params = @{},
        [string]$Uri = "http://127.0.0.1:8765/rpc",
        [int]$TimeoutSec = 600
    )

    $body = @{
        jsonrpc = "2.0"
        method = $Method
        params = $Params
        id = [guid]::NewGuid().ToString()
    } | ConvertTo-Json -Depth 50

    $response = Invoke-RestMethod -Method Post -Uri $Uri -ContentType "application/json" -Body $body -TimeoutSec $TimeoutSec
    if ($null -ne $response.error) {
        $reason = if ($response.error.data -and $response.error.data.reason) { " ($($response.error.data.reason))" } else { "" }
        throw "TBtools RPC error $($response.error.code): $($response.error.message)$reason"
    }
    return $response.result
}

macOS / Linux (bash + curl)

tbtools_rpc() {
    local method="$1"
    local params="${2:-{}}"
    local uri="${TBTOOLS_RPC_URI:-http://127.0.0.1:8765/rpc}"
    curl -s --max-time 600 -X POST "$uri" \
        -H "Content-Type: application/json" \
        -d "{\"jsonrpc\":\"2.0\",\"method\":\"$method\",\"params\":$params,\"id\":\"1\"}"
}

Discovery:

# Windows
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8765/health
Invoke-TBtoolsRpc -Method system.ping
$methods = (Invoke-TBtoolsRpc -Method system.listMethods).methods
$methods | Where-Object { $_ -like "*Fasta*" }
Invoke-TBtoolsRpc -Method system.describeMethod -Params @{ method = "FastaStat.process" }
Invoke-TBtoolsRpc -Method system.toolsJson

# macOS / Linux
curl -s http://127.0.0.1:8765/health
tbtools_rpc system.ping
tbtools_rpc system.listMethods | python3 -c "import sys,json; [print(m) for m in json.load(sys.stdin)['result']['methods']]"
tbtools_rpc system.describeMethod '{"method":"FastaStat.process"}'

RPC Workflow

  1. Create deterministic workspace folders and pass absolute host-local file paths. RPC bodies carry paths, not file content.
  2. Call system.listMethods and system.describeMethod for candidate methods. Use system.toolsJson when many method schemas are needed.
  3. Prefer a matching *.validateParams or *.validateInput before *.process when available.
  4. Treat validation failures carefully: validate methods may return result.ok = false / validated = false with structured errors instead of a JSON-RPC error.
  5. For long BLAST, tree, heatmap, NCBI, or large file jobs, raise client timeout and reduce concurrency.
  6. If JSON-RPC error -32603 has error.data.reason = rpc pool busy, back off and retry with lower concurrency.

RPC Protocol Notes

TopicContract
RequestHTTP POST /rpc, JSON-RPC 2.0 object with method, params, id
BatchJSON array of request objects; response array is in order and omits notifications
Empty batchHTTP 200 with body []
HealthGET /health returns HTTP 200 body OK
Successresult object, usually at least ok: true
ErrorsHTTP 200 with error.code, error.message, optional error.data

Common error codes: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error, -32000 timeout.

Common RPC Methods

AreaMethods
Sequence filesFastaStat.process, FastaSeqManipulator.process, AmazingFastaExtract.process, FastaExtract.process, FastxExtract.process, FastxIndex.process, FastaIDTools.*
FASTA conversionFastaToTable.process, TableToFasta.process, CdsToProtein.process, FastaMerge.process, FastaSplitByCount.process, FastaSplitAsOneSeq.process
AnnotationGXFFix.process, GffCdsPhase.process, GxfSeqExtract.process, GxfFilter.process, GffFeatureExtract.process, GtfFeatureExtract.process, GxfStat.process
TablesTableTools.transpose, TableTools.mergeByKeyMulti, TableTools.selectRows, TableTools.selectColumnsByList, TableTools.groupAggregate, TableRowManipulator.process
ExpressionExpressionFpkmToTpm.process, ExpressionRpkm.process, ExpressionTpm.process, ExpressionTau.process, ExpressionCorrMatrix.process, GeneExpFilter.process, GenePairCorr.process
Alignment and treesBlastCompareTwoSeqSet.process, BlastXmlToTable.process, ReciprocalBlast.process, OneStepBuildATree.process, TrimMsaSimple.process, TrimMsaGblocks.process, BlatAlign.process
Visualization and miscAmazingHeatMap.process, MemeSuiteXmlToTab.process, PlantCareClassify.process, SendEmail.process, TodoList.*

Examples

FASTA statistics (Windows PowerShell):

Invoke-TBtoolsRpc -Method FastaStat.process -Params @{
    inputPath = "D:/data/genome.fa"
    outputPath = "D:/data/out/genome_stat.xls"
    options = @{ getLengthOnly = $false }
}

FASTA statistics (macOS / Linux bash):

tbtools_rpc FastaStat.process \
  '{"inputPath":"/data/genome.fa","outputPath":"/data/out/genome_stat.xls","options":{"getLengthOnly":false}}'

Extract FASTA records with a prewritten ID list (Windows PowerShell):

Invoke-TBtoolsRpc -Method AmazingFastaExtract.process -Params @{
    inputPath = "D:/data/genome.fa"
    idListPath = "D:/data/ids.txt"
    outputPath = "D:/data/out/extracted.fa"
    options = @{
        usePattern = $false
        caseInsensitive = $true
        dontTreatSpaceAsColSep = $false
        wholeWordMatch = $false
    }
}

Validate then run a tree pipeline (Windows PowerShell):

$params = @{
    inputPath = "D:/data/sequences.fa"
    outputPath = "D:/data/out/tree"
    options = @{ ultraFastBS = $true; bbTime = 5000; model = "Auto"; threads = 2 }
}
$check = Invoke-TBtoolsRpc -Method OneStepBuildATree.validateParams -Params $params
if ($check.ok -eq $false -or $check.validated -eq $false) { $check.errors; throw "TBtools validation failed" }
Invoke-TBtoolsRpc -Method OneStepBuildATree.process -Params $params -TimeoutSec 7200

Validate then run a tree pipeline (macOS / Linux bash):

tbtools_rpc OneStepBuildATree.validateParams \
  '{"inputPath":"/data/sequences.fa","outputPath":"/data/out/tree","options":{"ultraFastBS":true,"bbTime":5000,"model":"Auto","threads":2}}'
tbtools_rpc OneStepBuildATree.process \
  '{"inputPath":"/data/sequences.fa","outputPath":"/data/out/tree","options":{"ultraFastBS":true,"bbTime":5000,"model":"Auto","threads":2}}'

Operating Rules

  • Detect the platform first: use PowerShell helpers on Windows, bash + curl on macOS/Linux.
  • Use TBtools bundled bin/ tools before suggesting external installs.
  • Keep stderr/error details visible for external tools and RPC errors.
  • Do not assume a method exists from memory; discover it through system.listMethods.
  • Do not assume system.listMethods returns a raw array; the canonical result is an object with methods.
  • Do not use Python helpers for normal TBtools work in this environment.
  • Use forward-slash paths (/data/...) in RPC calls even on Windows — TBtools accepts them.