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_KEY - AWS_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
INLINECODE15	Index of all pages (title + URL + description)
INLINECODE16

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: INLINECODE20

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

CODEBLOCK0

Source: github.com/the-omics-os/lobster |
PyPI: pypi.org/project/lobster-ai

Routing Table

You want to...	Docs slug	Skill reference
Install & configure	INLINECODE24	--
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: INLINECODE41

Hard Rules

1. 1. Always use --session-id for multi-step analyses -- loaded data persists across queries
2. Use lobster command --json for workspace inspection (no tokens burned, ~300ms)
3. Research Agent is the ONLY agent with internet access -- all others operate on loaded data
4. Never skip QC before analysis -- always assess quality first
5. Use --json flag when parsing output programmatically
6. Check data is loaded before running analysis steps (lobster command data --json)
7. Default workspace: .lobster_workspace/ -- override with INLINECODE47
8. 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: INLINECODE49