---

简体中文：README.zh.md · 命令行加上 --lang zh，或设置 LOBSTER_LANG=zh。

Quickstart

1. Install Lobster AI (macOS/Linux):

curl -fsSL https://install.lobsterbio.com -o install.sh && bash install.sh

(Download first, then run: the installer asks interactive questions that a piped curl | bash cannot read. Windows users: irm https://install.lobsterbio.com/windows | iex)

2. Configure your LLM (skip if you already chose a provider during install):

lobster init

Pick a provider — Omics-OS Cloud (managed, API key from app.omics-os.com/account), Anthropic, Gemini, or a local Ollama.

Non-interactive setup (agents, CI, scripts):

export OMICS_OS_API_KEY="..."             # from app.omics-os.com/account
lobster init --non-interactive --global --use-omics-os --skip-extras
lobster status                            # shows configuration, not account proof
lobster config-test --json                # optional: one real connectivity check

Watch: installation & init walkthrough

3. Start an interactive session:

lobster chat

Then describe your analysis in plain language:

> Search PubMed for single-cell CRISPR screens in T cells from 2023–2024,
  download the most cited dataset, run QC, integrate batches with Harmony,
  cluster the cells, annotate cell types, and export a notebook of the recorded steps.

Watch: analysis session walkthrough

CLI Reference

Core commands:

lobster chat                        # Interactive session (default)
lobster query "your request"        # Single-turn, non-interactive
lobster init                        # Configure LLM provider and API keys
lobster --help                      # Full command reference

Session continuity:

lobster query --session-id my_project "Search PubMed for CRISPR"
lobster query --session-id latest "Download the first result"  # resume last session

In-session slash commands (inside lobster chat):

> /pipeline export                  # Export the recorded analysis steps as a Jupyter notebook
> /pipeline run analysis.ipynb      # Re-run an exported notebook
> /data                             # List loaded datasets and modalities
> /files                            # Browse workspace files
> /status                           # Session info, token usage, active agents
> /help                             # All slash commands

Developer commands:

lobster scaffold agent --name my_expert --display-name "My Expert" \
  --description "Description" --tier free   # Generate a new agent package
lobster validate-plugin ./lobster-my/       # Validate package structure and AQUADIF contract

🤖 For AI Coding Agents

Install skills that give Claude Code, Cursor, or Gemini CLI deep knowledge of the Lobster architecture:

curl -fsSL https://skills.lobsterbio.com | bash

This installs lobster-use (analysis workflows) and lobster-dev (agent development). With these loaded, your coding agent understands the full 10-package structure, tool patterns, entry point registration, and AQUADIF contract — without needing to read source code manually.

Scaffold a new agent package from the command line:

lobster scaffold agent \
  --name epigenomics_expert \
  --display-name "Epigenomics Expert" \
  --description "ATAC-seq, ChIP-seq, and DNA methylation analysis" \
  --tier free

Generates a complete, contract-compliant package: pyproject.toml, entry point wiring, tool stubs with AQUADIF metadata, and contract tests. Then point your coding agent at the generated scaffolding and ask it to implement the domain logic.

Use Cases

End-to-end walkthroughs across omics domains:

Domain	Case Study
Single-Cell Transcriptomics	Cell clustering, annotation & trajectory inference
CML Drug Resistance	Resistance mechanism discovery from scRNA-seq
Drug Discovery	Target identification & compound prioritization
Clinical Genomics	Variant annotation & GWAS analysis
Mass Spec Proteomics	Biomarker panel selection from DIA-NN data
Literature Mining	Automated dataset discovery from PubMed
Multi-Omics ML	Feature selection & survival analysis

🧠 Architecture

Lobster AI is a multi-agent system: specialist agents for each omics domain, orchestrated by a LangGraph supervisor.

• Local execution: Analysis runs on your machine. Your data files stay on your machine; messages and tool results are sent to the LLM provider you configure (with a local model such as Ollama, they stay on your machine too).
• Scientific libraries: Agents call Scanpy, PyDESeq2, Harmony and others through tool functions. Some agents also have a code tool for custom analysis, which you can switch off per agent.
• Provenance: Analysis steps are recorded and can be exported as a Jupyter notebook.

🛠️ Build Your Own Agent

New agents are standalone packages that plug into Lobster via Python entry points. The lobster-dev skill loads the full architecture reference into your coding agent (Claude Code, Gemini CLI, Cursor) — package layout, tool patterns, AQUADIF contract, and test fixtures. Use lobster scaffold to generate the package skeleton, then let your coding agent implement the domain logic.

1. The Request

2. The Result

FAQ

What omics domains are supported?

Domain	Input Formats	Key Capabilities
Single-Cell RNA-seq	AnnData, 10x, h5ad	QC, doublet detection (Scrublet), batch integration (Harmony/scVI), clustering, cell type annotation, trajectory inference (DPT/PAGA)
Bulk RNA-seq	Salmon, kallisto, featureCounts	Sample QC, normalization (DESeq2/VST/CPM), differential expression (PyDESeq2), GSEA, publication-ready export
Genomics	VCF, PLINK	GWAS, LD pruning, kinship estimation, association testing, result clumping
Clinical Genomics	VCF, ClinVar, gnomAD	Variant annotation (VEP), pathogenicity scoring, clinical variant prioritization
Mass Spec Proteomics	MaxQuant, DIA-NN, Spectronaut	PTM analysis (phospho/acetyl/ubiquitin), peptide-to-protein rollup, batch correction
Affinity Proteomics	Olink NPX, SomaScan ADAT, Luminex MFI	LOD quality filtering, bridge normalization, cross-platform concordance
Proteomics Downstream	Any loaded proteomics modality	GO/Reactome/KEGG enrichment, kinase enrichment (KSEA), STRING PPI, biomarker panel selection (LASSO/Boruta)
Metabolomics	LC-MS, GC-MS, NMR	QC (RSD/TIC), imputation, normalization (PQN/TIC/IS), PCA, PLS-DA, OPLS-DA, m/z annotation (HMDB/KEGG), lipid class analysis
Machine Learning	Any modality	Feature selection (stability/LASSO/variance), survival analysis (Cox/KM), cross-validation, SHAP, multi-omics integration (MOFA)
Research & Data Access	—	PubMed/GEO/PRIDE/MetaboLights search, dataset download orchestration, metadata harmonization

Which LLMs can I use?

Configure via lobster init or environment variables. All providers use the same agent interface.

Provider	Type	Setup	Notes
Anthropic	Cloud	API key	Claude models — recommended default
Ollama	Local	ollama pull <model>	Local model: no messages go to an LLM provider (online database searches still use the internet)
OpenAI	Cloud	API key	GPT and o-series models
OpenRouter	Cloud	API key	Access 200+ models via a single endpoint
Nebius AI Studio	Cloud	API key	Open-weight models (Qwen, DeepSeek, GLM, Kimi)
Google Gemini	Cloud	Google API key	Long context window
AWS Bedrock	Cloud	AWS credentials	Enterprise compliance, IAM-based auth
Azure AI	Cloud	Endpoint + credential	Azure-hosted deployments

Pipeline export and slash commands

lobster chat
> /pipeline export         # Export a Jupyter notebook of the recorded steps
> /pipeline list           # List exported pipelines
> /pipeline run analysis.ipynb geo_gse109564
> /data                    # Show loaded datasets
> /status                  # Session info
> /help                    # All commands

Headless re-runs: execute the exported notebook with Papermill — only names in the notebook's parameters cell can be overridden:

papermill analysis.ipynb output.ipynb -p input_data "new_dataset.h5ad"

Advanced installation (Windows, pip)

Windows (PowerShell):

irm https://install.lobsterbio.com/windows | iex

uv (recommended manual install):

uv tool install 'lobster-ai[full]'   # All bundled domains (transcriptomics, genomics,
                                     #  proteomics) + metadata assistant; provider at init
lobster init

Optional domains ship as separate packages — add them to the same tool environment:

uv tool install 'lobster-ai[full]' --with lobster-metabolomics --with lobster-ml \
  --with lobster-drug-discovery --with lobster-structural-viz

Re-running uv tool install rebuilds the tool environment: extras and --with packages reset to whatever the new command includes — list them again when upgrading.

pip:

pip install 'lobster-ai[full]'
lobster init

Upgrade:

uv tool upgrade lobster-ai    # uv
pip install -U lobster-ai      # pip

How do I build my own agent?

Agents are standalone Python packages that register via PEP 517 entry points. No changes to core required — Lobster discovers them automatically at startup.

1. Scaffold the package:

lobster scaffold agent \
  --name my_domain_expert \
  --display-name "My Domain Expert" \
  --description "Analysis for [your domain]" \
  --tier free

2. Implement your tools in the generated tools/ directory. Each tool must declare AQUADIF metadata:

@tool
def run_analysis(modality_name: str) -> str:
    """Run domain-specific analysis on a loaded modality."""
    ...

run_analysis.metadata = {"categories": ["ANALYZE"], "provenance": True}
run_analysis.tags = ["ANALYZE"]

3. Validate the package structure before wiring:

lobster validate-plugin ./lobster-my_domain/

4. Install and test:

cd lobster-my_domain && uv venv --python 3.12 .venv && source .venv/bin/activate
uv pip install -e . pytest
pytest -m contract  # runs all AQUADIF contract checks

Install the lobster-dev skill to give your coding agent the complete reference — package layout, AGENT_CONFIG pattern, factory function signature, tool design rules, and the full validation checklist:

curl -fsSL https://skills.lobsterbio.com | bash

Acknowledgements

	Structural inspiration for the drug discovery agent package — CLI design patterns and domain decomposition.
	Foundation for the lobster-use and lobster-dev skills — domain knowledge structure and skill distribution patterns.
	UI component architecture and streaming patterns used in the Omics-OS Cloud frontend.
	BubbleTea, Lipgloss, Glamour, and huh — the entire terminal UI stack powering lobster chat.

Multi-omics data infrastructure for foundation models & biotech.

Omics-OS  ·  Lobster AI  ·  Docs