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:
lobster CLI (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_KEY for faster PubMed/GEO
- Writes:
.lobster_workspace/ (data, credentials in .env mode 0600, outputs)
- Global config (
--global flag, 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-id for multi-step analyses -- loaded data persists across queries
- Use
lobster command --json for 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
--json flag 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
1---2name: lobster-use3description: Runs bioinformatics analysis with Lobster AI -- single-cell RNA-seq, bulk RNA-seq, genomics (VCF/GWAS), proteomics (mass spec/affinity), metabolomics (LC-MS/GC-MS/NMR), machine learning (feature selection, survival analysis), drug discovery, literature search, dataset discovery, and visualization. Use when working with biological data, omics analysis, or bioinformatics tasks. Covers: H5AD, CSV, VCF, PLINK, 10X, mzML formats, GEO/SRA/PRIDE/MetaboLights accessions. TRIGGER PHRASES: "analyze cells", "search PubMed", "download GEO", "run QC", "cluster", "find markers", "differential expression", "UMAP", "volcano plot", "single-cell", "RNA-seq", "VCF", "GWAS", "proteomics", "mass spec", "metabolomics", "MetaboLights", "LC-MS", "metabolite", "feature selection", "survival analysis", "biomarker", "bioinformatics", "drug discovery", "pharmacogenomics", "variant annotation" ASSUMES: Lobster is installed and configured. For setup issues, tell user to run `lobster config-test` and fix any errors before proceeding.4---56# Lobster AI Usage Guide78Lobster AI is a multi-agent bioinformatics platform. Users describe analyses in natural9language -- Lobster routes to 22 specialist agents across 10 packages automatically.1011## Requirements1213- **Binaries**: `lobster` CLI (`pip install lobster-ai`), Python 3.12+14- **Credential**: Exactly ONE LLM provider key as env var (not all — pick one):15 - `ANTHROPIC_API_KEY` | `GOOGLE_API_KEY` | `OPENAI_API_KEY` | `OPENROUTER_API_KEY`16 - `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (Bedrock — both required)17 - `AZURE_AI_ENDPOINT` + `AZURE_AI_CREDENTIAL` (Azure — both required)18 - Ollama: no key needed (local models)19- **Optional**: `NCBI_API_KEY` for faster PubMed/GEO20- **Writes**: `.lobster_workspace/` (data, credentials in `.env` mode 0600, outputs)21- **Global config** (`--global` flag, NOT default): `~/.config/lobster/` — avoid unless needed22- **Network**: LLM provider API + public bio databases (GEO, SRA, PRIDE, MetaboLights)2324## Docs Discovery2526The docs site at **docs.omics-os.com** exposes LLM-friendly raw markdown:2728| Route | Use |29|-------|-----|30| `/llms.txt` | Index of all pages (title + URL + description) |31| `/llms-full.txt` | Full content dump of all free pages |32| `/raw/docs/{slug}.md` | Raw markdown for a specific page |3334**Workflow**: Fetch `/llms.txt` first to discover slugs, then fetch individual pages via `/raw/docs/{slug}.md`.3536Example: `https://docs.omics-os.com/raw/docs/tutorials/single-cell-rnaseq.md`3738## Two Modes3940This skill supports coding agents in two modes:4142**Orchestrator** -- The agent calls `lobster query --json --session-id` programmatically,43parses structured output, and chains multi-step analyses. See [agent-patterns.md](references/agent-patterns.md).4445**Guide** -- The agent teaches a human user what to type in `lobster chat` or `lobster query`.46See the routing table below for which docs page to fetch.4748## Quick Start4950```bash51# Install (PyPI -- preferred)52pip install 'lobster-ai[full]'53# or: uv tool install 'lobster-ai[full]'5455# Configure (uses env var -- never pass raw keys on command line)56lobster init --non-interactive --anthropic-key "$ANTHROPIC_API_KEY" --profile production5758# Run analysis (always pass -w and --session-id together)59lobster query -w ./my_analysis --session-id "proj" --json "Download GSE109564 and run QC"6061# Inspect workspace (no tokens burned, ~300ms)62lobster command data --json -w ./my_analysis63```6465**Source**: [github.com/the-omics-os/lobster](https://github.com/the-omics-os/lobster) |66**PyPI**: [pypi.org/project/lobster-ai](https://pypi.org/project/lobster-ai/)6768## Routing Table6970| You want to... | Docs slug | Skill reference |71|---|---|---|72| **Install & configure** | `getting-started/installation` | -- |73| **Configuration options** | `getting-started/configuration` | -- |74| **Use the CLI** | `guides/cli-commands` | [cli-reference.md](references/cli-reference.md) |75| **Orchestrate programmatically** | -- | [agent-patterns.md](references/agent-patterns.md) |76| **Analyze scRNA-seq** | `tutorials/single-cell-rnaseq` | -- |77| **Analyze bulk RNA-seq** | `tutorials/bulk-rnaseq` | -- |78| **Analyze proteomics** | `tutorials/proteomics` | -- |79| **Understand data formats** | `guides/data-formats` | -- |80| **Search literature / datasets** | `agents/research` | -- |81| **Analyze genomics** | `agents/genomics` | -- |82| **Analyze metabolomics** | `case-studies/metabolomics` | -- |83| **ML / feature selection** | `agents/ml` | -- |84| **Drug discovery** | `agents/drug-discovery` | -- |85| **Visualize results** | `agents/visualization` | -- |86| **Troubleshoot** | `support/troubleshooting` | -- |87| **See case studies** | `case-studies/{domain}` | -- |88| **All agent capabilities** | `agents` | -- |89| **Extend Lobster (dev)** | -- | Use `lobster-dev` skill |9091To fetch a docs page: `https://docs.omics-os.com/raw/docs/{slug}.md`9293## Hard Rules94951. **Always use `--session-id`** for multi-step analyses -- loaded data persists across queries962. **Use `lobster command --json`** for workspace inspection (no tokens burned, ~300ms)973. **Research Agent is the ONLY agent with internet access** -- all others operate on loaded data984. **Never skip QC** before analysis -- always assess quality first995. **Use `--json` flag** when parsing output programmatically1006. **Check data is loaded** before running analysis steps (`lobster command data --json`)1017. **Default workspace**: `.lobster_workspace/` -- override with `-w <path>`1028. **Fetch docs on demand** from `docs.omics-os.com/raw/docs/{slug}.md` -- don't guess workflows103104## Agent Overview10510622 agents across 10 packages. Supervisor routes automatically based on natural language.107108| Agent | Package | Handles |109|---|---|---|110| Supervisor | lobster-ai | Routes queries, coordinates agents |111| Research Agent | lobster-research | PubMed, GEO, SRA, PRIDE, MetaboLights search (online) |112| Data Expert | lobster-research | File loading, downloads, format conversion (offline) |113| Transcriptomics Expert | lobster-transcriptomics | scRNA-seq + bulk RNA-seq: QC, clustering, trajectory |114| Annotation Expert | lobster-transcriptomics | Cell type annotation, gene set enrichment (child) |115| DE Analysis Expert | lobster-transcriptomics | Differential expression, pseudobulk, GSEA (child) |116| Proteomics Expert | lobster-proteomics | MS + affinity import, QC, normalization, batch correction |117| Proteomics DE Expert | lobster-proteomics | Protein DE, pathway enrichment, KSEA, STRING PPI (child) |118| Biomarker Discovery | lobster-proteomics | Panel selection, nested CV, hub proteins (child) |119| Metabolomics Expert | lobster-metabolomics | LC-MS/GC-MS/NMR: QC, normalization, PCA/PLS-DA, annotation |120| Genomics Expert | lobster-genomics | VCF/PLINK: QC, GWAS, variant annotation |121| Variant Analysis Expert | lobster-genomics | VEP annotation, ClinVar, clinical prioritization (child) |122| ML Expert | lobster-ml | ML prep, scVI embeddings, data export |123| Feature Selection Expert | lobster-ml | Stability selection, LASSO, variance filtering (child) |124| Survival Analysis Expert | lobster-ml | Cox models, Kaplan-Meier, risk stratification (child) |125| Drug Discovery Expert | lobster-drug-discovery | Drug target validation, compound profiling |126| Cheminformatics Expert | lobster-drug-discovery | Molecular descriptors, fingerprints, similarity (child) |127| Clinical Dev Expert | lobster-drug-discovery | Trial design, endpoint analysis, safety signals (child) |128| Pharmacogenomics Expert | lobster-drug-discovery | PGx variants, drug-gene interactions (child) |129| Visualization Expert | lobster-visualization | UMAP, heatmaps, volcano plots, dot plots (Plotly) |130| Metadata Assistant | lobster-metadata | ID mapping, metadata standardization (internal) |131| Protein Structure Viz | lobster-structural-viz | PDB fetch, PyMOL visualization, RMSD |132133Per-agent docs: `https://docs.omics-os.com/raw/docs/agents/{domain}.md`
dvcrn