Lobster AI Usage Guide
Lobster AI is a multi-agent bioinformatics platform. Users describe analyses in natural language -- Lobster routes to 22 specialist agents across 10 packages automatically.
Requirements
- Binaries:
lobsterCLI (pip install lobster-ai), Python 3.12+ - Credential: Exactly ONE LLM provider key as env var (not all — pick one):
ANTHROPIC_API_KEY|GOOGLE_API_KEY|OPENAI_API_KEY|OPENROUTER_API_KEYAWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY(Bedrock — both required)AZURE_AI_ENDPOINT+AZURE_AI_CREDENTIAL(Azure — both required)- Ollama: no key needed (local models)
- Optional:
NCBI_API_KEYfor faster PubMed/GEO - Writes:
.lobster_workspace/(data, credentials in.envmode 0600, outputs) - Global config (
--globalflag, NOT default):~/.config/lobster/— avoid unless needed - Network: LLM provider API + public bio databases (GEO, SRA, PRIDE, MetaboLights)
Docs Discovery
The docs site at docs.omics-os.com exposes LLM-friendly raw markdown:
| Route | Use |
|---|---|
/llms.txt | Index of all pages (title + URL + description) |
/llms-full.txt | Full content dump of all free pages |
/raw/docs/{slug}.md | Raw markdown for a specific page |
Workflow: Fetch /llms.txt first to discover slugs, then fetch individual pages via /raw/docs/{slug}.md.
Example: https://docs.omics-os.com/raw/docs/tutorials/single-cell-rnaseq.md
Two Modes
This skill supports coding agents in two modes:
Orchestrator -- The agent calls lobster query --json --session-id programmatically,
parses structured output, and chains multi-step analyses. See agent-patterns.md.
Guide -- The agent teaches a human user what to type in lobster chat or lobster query.
See the routing table below for which docs page to fetch.
Quick Start
# Install (PyPI -- preferred)
pip install 'lobster-ai[full]'
# or: uv tool install 'lobster-ai[full]'
# Configure (uses env var -- never pass raw keys on command line)
lobster init --non-interactive --anthropic-key "$ANTHROPIC_API_KEY" --profile production
# Run analysis (always pass -w and --session-id together)
lobster query -w ./my_analysis --session-id "proj" --json "Download GSE109564 and run QC"
# Inspect workspace (no tokens burned, ~300ms)
lobster command data --json -w ./my_analysis
Source: github.com/the-omics-os/lobster | PyPI: pypi.org/project/lobster-ai
Routing Table
| You want to... | Docs slug | Skill reference |
|---|---|---|
| Install & configure | getting-started/installation | -- |
| Configuration options | getting-started/configuration | -- |
| Use the CLI | guides/cli-commands | cli-reference.md |
| Orchestrate programmatically | -- | agent-patterns.md |
| Analyze scRNA-seq | tutorials/single-cell-rnaseq | -- |
| Analyze bulk RNA-seq | tutorials/bulk-rnaseq | -- |
| Analyze proteomics | tutorials/proteomics | -- |
| Understand data formats | guides/data-formats | -- |
| Search literature / datasets | agents/research | -- |
| Analyze genomics | agents/genomics | -- |
| Analyze metabolomics | case-studies/metabolomics | -- |
| ML / feature selection | agents/ml | -- |
| Drug discovery | agents/drug-discovery | -- |
| Visualize results | agents/visualization | -- |
| Troubleshoot | support/troubleshooting | -- |
| See case studies | case-studies/{domain} | -- |
| All agent capabilities | agents | -- |
| Extend Lobster (dev) | -- | Use lobster-dev skill |
To fetch a docs page: https://docs.omics-os.com/raw/docs/{slug}.md
Hard Rules
- Always use
--session-idfor multi-step analyses -- loaded data persists across queries - Use
lobster command --jsonfor workspace inspection (no tokens burned, ~300ms) - Research Agent is the ONLY agent with internet access -- all others operate on loaded data
- Never skip QC before analysis -- always assess quality first
- Use
--jsonflag when parsing output programmatically - Check data is loaded before running analysis steps (
lobster command data --json) - Default workspace:
.lobster_workspace/-- override with-w <path> - Fetch docs on demand from
docs.omics-os.com/raw/docs/{slug}.md-- don't guess workflows
Agent Overview
22 agents across 10 packages. Supervisor routes automatically based on natural language.
| Agent | Package | Handles |
|---|---|---|
| Supervisor | lobster-ai | Routes queries, coordinates agents |
| Research Agent | lobster-research | PubMed, GEO, SRA, PRIDE, MetaboLights search (online) |
| Data Expert | lobster-research | File loading, downloads, format conversion (offline) |
| Transcriptomics Expert | lobster-transcriptomics | scRNA-seq + bulk RNA-seq: QC, clustering, trajectory |
| Annotation Expert | lobster-transcriptomics | Cell type annotation, gene set enrichment (child) |
| DE Analysis Expert | lobster-transcriptomics | Differential expression, pseudobulk, GSEA (child) |
| Proteomics Expert | lobster-proteomics | MS + affinity import, QC, normalization, batch correction |
| Proteomics DE Expert | lobster-proteomics | Protein DE, pathway enrichment, KSEA, STRING PPI (child) |
| Biomarker Discovery | lobster-proteomics | Panel selection, nested CV, hub proteins (child) |
| Metabolomics Expert | lobster-metabolomics | LC-MS/GC-MS/NMR: QC, normalization, PCA/PLS-DA, annotation |
| Genomics Expert | lobster-genomics | VCF/PLINK: QC, GWAS, variant annotation |
| Variant Analysis Expert | lobster-genomics | VEP annotation, ClinVar, clinical prioritization (child) |
| ML Expert | lobster-ml | ML prep, scVI embeddings, data export |
| Feature Selection Expert | lobster-ml | Stability selection, LASSO, variance filtering (child) |
| Survival Analysis Expert | lobster-ml | Cox models, Kaplan-Meier, risk stratification (child) |
| Drug Discovery Expert | lobster-drug-discovery | Drug target validation, compound profiling |
| Cheminformatics Expert | lobster-drug-discovery | Molecular descriptors, fingerprints, similarity (child) |
| Clinical Dev Expert | lobster-drug-discovery | Trial design, endpoint analysis, safety signals (child) |
| Pharmacogenomics Expert | lobster-drug-discovery | PGx variants, drug-gene interactions (child) |
| Visualization Expert | lobster-visualization | UMAP, heatmaps, volcano plots, dot plots (Plotly) |
| Metadata Assistant | lobster-metadata | ID mapping, metadata standardization (internal) |
| Protein Structure Viz | lobster-structural-viz | PDB fetch, PyMOL visualization, RMSD |
Per-agent docs: https://docs.omics-os.com/raw/docs/agents/{domain}.md