opencode-bioinformatics

Bioinformatics domain plugin for OpenCode.

Status: Experimental pre-alpha. Core plugin architecture, mode routing, typed tools, Biomni integration, and run-state persistence are implemented, but parts of the planning workflow and release surface are still evolving.

It adds a mode-aware bioinformatics agent with typed bioinformatics tools and reproducibility-focused workflow behavior.

The project is aimed at a specific gap in bioinformatics workflow practice:

• community-standardized pipelines are now common, especially in the Nextflow era
• bioinformatics pipelines could be robust before they were standardized, but standardization still did not solve customization
• many users still struggle to connect biological intent with computational implementation

opencode-bioinformatics is intended to become the first place to develop agent-based bioinformatics pipelines by adapting standardized workflows instead of starting from ad hoc scripts.

What You Get

• one primary agent: bioinformatics
• three specialist subagents:
  • bioinformatics_librarian
  • bioinformatics_reproducibility
  • bioinformatics_executor
• two explicit operating modes: discovery, analysis
• slash command mode switching: /discovery, /analysis, /analyze
• concrete specialist-role architecture (coordinator + librarian/reproducibility/executor)
• planning-focus commands for intake, overall plan, fact sheet, and decision sheet
• persistent managed Markdown artifacts: .opencode/computational-plan.md, .opencode/biological-plan.md
• persistent project run state: .opencode/bioinformatics-run-state.json
• mode instructions injected as hidden system prompt context (not shown in user chat text)
• typed file-format tools (parse_fasta, validate_fasta, parse_fastq)
• reference, workflow-blueprint, and provenance-report tools
• Biomni-backed genomics tools (scRNA, genetics, cancer genomics, reference queries)
• optional strict run-contract mode via .opencode/bioinformatics-run.json
• plugin-level configuration with user/project overrides

Project Direction

The package is being positioned around three linked goals:

1. standardized pipeline adaptation standardized community workflows should be the starting point, not the ceiling; the plugin should help users customize and extend them safely
2. automation with educational value automation should teach both the computational and biological sides of the workflow, not hide them
3. LLM-native development the package is developed for LLM-assisted maintenance and is expected to remain LLM-maintained over time

Current runtime support is strongest around discovery, analysis, and planning-focus artifacts. The longer-term direction is to use Markdown artifacts across both modes so that important decisions and their rationale remain explicit in both the computational and biological views of a pipeline.

Prerequisites

OpenCode is required.

opencode --version

Bun is recommended for development and local execution.

bun --version

Install

bunx opencode-bioinformatics install

Optional Biomni bootstrap:

bunx opencode-bioinformatics install --install-biomni --python python3

Install Python + Biomni together (recommended when Python is not ready):

bunx opencode-bioinformatics install --install-python --install-biomni --python-version 3.11

What install does:

1. checks OpenCode availability
2. updates ~/.config/opencode/opencode.json plugin list
3. writes default plugin config
4. checks Python runtime for Biomni compatibility
5. optionally installs and selects a managed Python via uv (--install-python)
6. optionally installs Biomni (--install-biomni)

Notes:

• bun run build only compiles TypeScript outputs (the plugin bundle and CLI bundle); it does not install Python or Biomni.
• --install-python requires uv to be installed and available in PATH.

Then run:

opencode

Usage

Inside OpenCode, choose the bioinformatics agent.

Agents

Current runtime agents:

• bioinformatics
  • primary coordinator agent
• bioinformatics_librarian
  • tool/method evidence review specialist
• bioinformatics_reproducibility
  • reproducibility policy and promotion-readiness specialist
• bioinformatics_executor
  • approved-step execution specialist

Middleware / Hooks

Current runtime middleware/hooks:

• mode-router
  • mode switching, planning-focus commands, session agent tracking, and hidden system prompt injection
• bio-file-detector
  • detects referenced bioinformatics file names and injects format-aware guidance
• workflow-validator
  • injects intake/run-contract promotability rules and syncs managed project artifacts

Mode Commands

| Command | Mode | Purpose | | --- | --- | --- | | /discovery | Discovery | Tool/method exploration and comparison | | /analysis | Analysis | Reproducible workflow design and execution guidance | | /analyze | Analysis | Alias of /analysis |

Planning Focus Commands

| Command | Planning Focus | Purpose | | --- | --- | --- | | /intake | Intake | Collect missing required context before execution-ready plans | | /plan | Overall Plan | Track stages, blockers, next action, completion criteria | | /overall_plan | Overall Plan | Alias if another plugin/runtime already uses /plan | | /facts | Fact Sheet | Record factual context/evidence/uncertainty only | | /decisions | Decision Sheet | Record locked choices, rationale, assumptions, revisit triggers |

At present, these planning-focus commands change session state and hidden system guidance. Standalone persisted Fact Sheet / Decision Sheet Markdown files are not yet created by the runtime.

Mode Behavior

Discovery mode:

• compare tools and methods
• surface assumptions and risks
• recommend validation approach before implementation

Analysis mode:

• produce executable workflow structure
• enforce reproducibility details (versions, references, parameters)
• define expected artifacts and QC checkpoints

Available Tools

| Tool | Description | | --- | --- | | parse_fasta | Parse FASTA content into sequence records | | validate_fasta | Validate FASTA format and report errors/warnings | | parse_fastq | Parse FASTQ content into sequence + quality records | | validate_reference_bundle | Validate organism/reference-build compatibility and reference completeness | | create_workflow_blueprint | Create a structured workflow-stage blueprint with expected artifacts | | generate_provenance_report | Generate a structured provenance report from run metadata and artifacts |

Biomni-backed tool families are also enabled for the bioinformatics agent. For the full list, see:

• docs/biomni-genomics-tools.md

Strict Run Contract

If .opencode/bioinformatics-run.json exists, the plugin enables strict run-contract mode.

In strict mode it will:

• load and validate the project run contract
• derive and persist project promotion state
• surface missing contract fields and promotion state in system/compaction context
• block selected execution-oriented tools until the contract is promotable
• update managed computational/biological Markdown artifacts from the contract, intake state, and tool outputs

Project Run State

The plugin maintains .opencode/bioinformatics-run-state.json as a project-scoped runtime snapshot.

It records:

• current promotion status (draft, intake-pending, blocked, promotable)
• whether promotion is heuristic or strict run-contract based
• recent tool calls
• workflow stages and planned/declared artifacts
• provenance summary fields such as parameter snapshot hash and decision trace

This file is updated from intake changes, run-contract state, and post-tool execution bookkeeping.

Current Limitations

• Experimental pre-alpha: expect behavior and packaging details to change.
• Planning-focus commands are implemented, but only the computational plan, biological plan, and run-state files are currently persisted.
• Strict run-contract enforcement is limited to plugin-managed surfaces; it is not a full external workflow-engine enforcement layer.

Configuration

Config Paths

| Scope | Path | | --- | --- | | User | ~/.config/opencode/opencode-bioinformatics.json | | Project | .opencode/opencode-bioinformatics.json |

Project config overrides user config.

Example Config

{
  "default_mode": "discovery",
  "biomni": {
    "enabled": true,
    "python_command": "python3",
    "timeout_ms": 120000
  },
  "nextflow": {
    "version": "latest",
    "profile": "docker"
  },
  "disabled_hooks": [],
  "disabled_tools": [],
  "file_formats": {
    "auto_detect": true
  }
}

Architecture Summary

The package is designed as a contract-driven OpenCode plugin:

• OpenCode handles runtime protocol and lifecycle
• opencode-bioinformatics handles domain behavior and policy
• mode logic is session-scoped and explicit
• tools use typed schemas and structured outputs
• validation/provenance requirements are first-class concerns
• standardized workflows should be adapted rather than replaced wholesale
• educational value is carried through explicit computational and biological Markdown artifacts that record decisions and rationale across both modes
• documentation is intentionally structured to be legible to both human maintainers and LLM maintainers

See:

• sibling repo docs: ../openbioinfo-architecture/README.md
• target spec: ../openbioinfo-architecture/04_target_architecture_spec.md
• current implementation reference: ../openbioinfo-architecture/05_current_implementation_reference.md

Development

cd opencode-bioinformatics
bun install
bun run build
bun test

bun run build is compile-only, refreshes dist from a clean output directory, and has no runtime dependency side effects.

CLI

bunx opencode-bioinformatics install
bunx opencode-bioinformatics doctor
bunx opencode-bioinformatics version

Troubleshooting

Plugin does not load

1. Verify plugin entry exists in ~/.config/opencode/opencode.json.
2. Re-run bunx opencode-bioinformatics install.
3. Check OpenCode startup logs for plugin load errors.
4. Run bunx opencode-bioinformatics doctor for environment diagnostics.

Agent not visible

1. Confirm config.agent.bioinformatics is registered through plugin.
2. Restart OpenCode session.
3. Ensure plugin did not fail schema/config validation at startup.

Mode command not applied

1. Ensure active agent is bioinformatics.
2. Use exact slash commands (/discovery, /analysis, /analyze).
3. Check hook configuration (disabled_hooks) does not disable mode router.

Biomni tools fail at runtime

1. Run bunx opencode-bioinformatics doctor.
2. Confirm biomni.enabled is true in plugin config.
3. Confirm configured biomni.python_command points to Python >= 3.10.
4. If Biomni is from source, set biomni.python_path to the Biomni project path.

License

Business Source License 1.1 (BUSL-1.1).