Lobster AI Usage Guide
Lobster AI is a multi-agent bioinformatics platform. You interact via natural language or slash commands — Lobster routes to specialist agents automatically.
Installation
If Lobster is not installed, guide the user to the right command for their platform:
macOS / Linux
curl -fsSL https://install.lobsterbio.com | bash
Windows (PowerShell)
irm https://install.lobsterbio.com/windows | iex
Manual install (any platform)
uv tool install 'lobster-ai[full,anthropic]' && lobster init
# or: pip install 'lobster-ai[full]' && lobster init
After install, lobster init configures API keys and selects agent packages.
Upgrading
- uv tool:
uv tool upgrade lobster-ai - pip:
pip install --upgrade lobster-ai
Adding Agents (uv tool installs)
Users with uv tool installs add agents via:
uv tool install lobster-ai --with lobster-transcriptomics --with lobster-proteomics
Running lobster init will guide this process and generate the command.
Quick Reference
| Task | Reference |
|---|---|
| CLI commands | references/cli-commands.md |
| Single-cell analysis | references/single-cell-workflow.md |
| Bulk RNA-seq analysis | references/bulk-rnaseq-workflow.md |
| Literature & datasets | references/research-workflow.md |
| Visualization | references/visualization.md |
| Available agents | references/agents.md |
Interaction Modes
Interactive Chat
lobster chat # Start interactive session
lobster chat --workspace ./myproject # Custom workspace
lobster chat --reasoning # Enable detailed reasoning
Single Query
lobster query "Your request"
lobster query --session-id latest "Follow-up request"
Core Patterns
Natural Language (Primary)
Just describe what you want:
"Download GSE109564 and run quality control"
"Cluster the cells and find marker genes"
"Compare hepatocytes vs stellate cells"
Slash Commands (System Operations)
/data # Show loaded data info
/files # List workspace files
/workspace list # List available datasets
/workspace load 1 # Load dataset by index
/plots # Show generated visualizations
/save # Save current session
/status # Show system status
/help # All commands
Session Continuity
# Start named session
lobster query --session-id "my_analysis" "Load GSE109564"
# Continue with context
lobster query --session-id latest "Now cluster the cells"
lobster query --session-id latest "Find markers for cluster 3"
Agent System
Lobster routes to specialist agents automatically:
| Agent | Handles |
|---|---|
| Supervisor | Routes queries, coordinates agents |
| Research Agent | PubMed search, GEO discovery, paper extraction |
| Data Expert | File loading, format conversion, downloads |
| Transcriptomics Expert | scRNA-seq: QC, clustering, markers |
| DE Analysis Expert | Differential expression, statistical testing |
| Annotation Expert | Cell type annotation, gene set enrichment |
| Visualization Expert | UMAP, heatmaps, volcano plots |
| Proteomics Expert | Mass spec analysis [alpha] |
| Genomics Expert | VCF, GWAS, variant analysis [alpha] |
| ML Expert | Embeddings, classification [alpha] |
Workspace & Outputs
Default workspace: .lobster_workspace/
Output files:
| Extension | Content |
|---|---|
.h5ad | Processed AnnData objects |
.html | Interactive visualizations |
.png | Publication-ready plots |
.csv | Exported tables |
.json | Metadata, provenance |
Managing outputs:
/files # List all outputs
/plots # View visualizations
/open results.html # Open in browser
/read summary.csv # Preview file contents
Typical Workflow
# 1. Start session
lobster chat --workspace ./my_analysis
# 2. Load or download data
"Download GSE109564 from GEO"
# or
/workspace load my_data.h5ad
# 3. Quality control
"Run quality control and show me the metrics"
# 4. Analysis
"Filter low-quality cells, normalize, and cluster"
# 5. Interpretation
"Identify cell types and find marker genes"
# 6. Visualization
"Create UMAP colored by cell type"
/plots
# 7. Export
"Export marker genes to CSV"
/save
Troubleshooting Quick Reference
| Issue | Check |
|---|---|
| Lobster not responding | lobster config-test |
| No data loaded | /data to verify, /workspace list to see available |
| Analysis fails | Try with --reasoning flag |
| Missing outputs | Check /files and workspace directory |
Documentation
Online docs: docs.omics-os.com
Key sections:
- Guides → CLI Commands
- Guides → Data Analysis Workflows
- Tutorials → Single-Cell RNA-seq
- Agents → Package documentation