Lobster Bioinformatics

Lobster requires an LLM provider (Ollama, Anthropic, or AWS Bedrock).

Pre-flight check (IMPORTANT)

Before running any analysis, always verify Lobster is ready:

lobster config-test --json

Returns structured JSON:

{
  "valid": true,
  "env_file": "/path/to/.env",
  "checks": {
    "llm_provider": {"status": "pass", "provider": "bedrock", "message": "Connected"},
    "ncbi_api": {"status": "pass", "has_key": true, "message": "Connected"},
    "workspace": {"status": "pass", "path": "/path/to/workspace", "message": "Writable"}
  }
}

This command validates:

• LLM provider - Ollama server running + models installed, or Anthropic/Bedrock API keys valid
• NCBI API - PubMed/GEO access (optional but recommended)
• Workspace - Directory writable for output files

Expected output for a working setup:

✅ LLM Provider: bedrock (connected)
✅ NCBI API: Connected (with API key)
✅ Workspace: Writable
✅ Configuration Valid

If config-test fails:

Quick status checks:

# Show configuration values (masked)
lobster config-show

# Show subscription tier and available agents
lobster status

Usage

Basic syntax

# Single query (non-interactive)
lobster query "<natural language request>"

# With custom workspace
lobster query --workspace /path/to/workspace "<request>"

# With reasoning mode (for complex tasks)
lobster query --reasoning "<request>"

Session continuity (multi-turn conversations)

Lobster supports conversation continuity via --session-id, enabling follow-up questions that reference previous context either by setting sessin-id to latest or a string of your choice:

# default session
lobster query "Search PubMed for CRISPR papers"
# Output: Session: session_20241208_150000 (use --session-id latest for follow-ups)
# then follow up with 
lobster query --session-id latest "Download the first dataset from that search"

#or use custom session id
lobster query --session-id "crispr_search_1" "Search PubMed for CRISPR papers"
#follow up with 
lobster query --session-id "crispr_search_1" "show me metadata from the first paper"

Best practices:

• Always use --session-id latest for follow-up queries
• Session files are saved in workspace as session_*.json
• Use same --workspace for related queries to maintain context
• Session contains conversation history, not tool execution state

Workspace-based sessions:

# Project 1: Cancer research
lobster query --workspace ~/cancer-project "Search for breast cancer datasets"
lobster query --workspace ~/cancer-project --session-id latest "Download the best one"

# Project 2: Immunology (separate session)
lobster query --workspace ~/immuno-project "Search for T cell datasets"
lobster query --workspace ~/immuno-project --session-id latest "Analyze that"

Common patterns

Single-cell analysis:

lobster query "Download GSE109564 and perform quality control"
lobster query "Cluster the dataset and find marker genes"
lobster query "Create UMAP visualization colored by cell type"

Literature mining:

lobster query "Search PubMed for CRISPR screens in cancer"
lobster query "Find papers about CAR-T therapy and extract their GEO datasets"
lobster query "Get the full text and methods section for PMID:12345678"

Dataset discovery:

lobster query "Search GEO for single-cell pancreatic beta cell datasets"
lobster query "Validate GSE200997 metadata for required fields: cell_type, tissue"
lobster query "Download SRA dataset SRP123456"

Data analysis:

lobster query "Load counts.csv and run differential expression analysis"
lobster query "Perform batch correction on the loaded dataset"
lobster query "Generate volcano plot for DE results"

Quality control:

lobster query "Assess quality metrics for the loaded dataset"
lobster query "Filter cells with <200 genes or >8000 genes"
lobster query "Identify doublets using scrublet"

Output handling

Lobster outputs are saved in the workspace directory (default: .lobster_workspace/):

Key files to check:

• *.h5ad - Processed datasets (AnnData format)
• *.html - Interactive visualizations
• *.png - Static plots for publications
• *.csv - Exported data tables
• *.json - Metadata and provenance

To read results:

# List workspace files
ls -lh .lobster_workspace/

# Read specific outputs
cat .lobster_workspace/analysis_summary.json

Integration workflow

Example 1: Analyze dataset and extract results

# Step 1: Run analysis
lobster query --session-id "gse109564" "Download GSE109564, run QC, and cluster cells"

# Step 2: Check outputs
ls .lobster_workspace/*.h5ad
ls .lobster_workspace/*.html

# Step 3: Extract specific data
lobster query --session-id "gse109564" "Export cluster markers to CSV"

# Step 4: Use results in your code
# Results are now in .lobster_workspace/markers.csv

Example 2: Literature mining workflow

# Step 1: Find papers
lobster query "Search for papers about immune checkpoint inhibitors in melanoma"

# Step 2: Extract datasets
lobster query "Extract all GEO dataset IDs from the cached papers"

# Step 3: Validate datasets
lobster query "Check which datasets have cell_type and treatment metadata"

# Step 4: Download best match
lobster query "Download the dataset with most samples"

Advanced features

Export reproducible notebooks:

lobster query "Export the analysis pipeline as a Jupyter notebook"
# Creates a Papermill-compatible notebook in workspace

Workspace management:

# Use custom workspace per project
lobster query --workspace ./project1-data "Analyze counts.csv"
lobster query --workspace ./project2-data "Analyze other-counts.csv"

Provider switching (if multiple LLM providers configured):

# Use specific provider
lobster query --provider ollama "Run expensive analysis"  # Free local
lobster query --provider anthropic "Quick task"  # Fast cloud

Troubleshooting

Command not found:

• Verify installation: which lobster
• Install: uv pip install lobster-ai
• Configure: lobster init

Rate limit errors:

• Using Anthropic? Switch to Ollama (free) or AWS Bedrock (enterprise)
• Wait 60 seconds and retry
• Configure Ollama: ollama pull llama3:8b-instruct && export LOBSTER_LLM_PROVIDER=ollama

Analysis errors:

• Check workspace: ls .lobster_workspace/
• View session log: cat ~/.lobster/.session.json
• Try with reasoning: lobster query --reasoning "<request>"

No output files:

• Verify workspace location: lobster query "show workspace info"
• Check for errors in command output
• Ensure request was analysis (not just information retrieval)

Tips for effective use

1. Be specific: Instead of "analyze data", say "perform single-cell clustering with resolution 0.5"
2. Chain operations: "Download GSE12345, run QC, cluster, and export markers to CSV"
3. Check outputs: Always verify generated files in .lobster_workspace/
4. Use reasoning mode: For complex multi-step tasks, add --reasoning flag
5. Provide context: Reference specific files, datasets, or previous results

Limitations

• Lobster requires active LLM provider (Ollama/Anthropic/Bedrock)
• Large datasets (>100K cells) may be slow depending on system resources
• Some features require premium subscription (proteomics, metadata assistant)
• Full-text paper access limited by journal availability
• Rate limits apply when using cloud LLM providers

Documentation

• Wiki: https://github.com/the-omics-os/lobster-local/wiki
• Examples: https://github.com/the-omics-os/lobster-local/wiki/27-examples-cookbook
• Installation: https://github.com/the-omics-os/lobster-local/wiki/02-installation
• Configuration: https://github.com/the-omics-os/lobster-local/wiki/03-configuration

Version

This Skill is compatible with:

• Lobster AI v0.3.1.4+
• Claude Code v1.0+

For issues or questions: https://github.com/the-omics-os/lobster-local/issues