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:

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

To fetch a docs page: https://docs.omics-os.com/raw/docs/{slug}.md

Hard Rules

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 -w <path>
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.

Per-agent docs: https://docs.omics-os.com/raw/docs/agents/{domain}.md