--- slug: "lobster-local" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/the-omics-os/lobster-local@main/README.md" repo: "https://github.com/the-omics-os/lobster-local" source_file: "README.md" branch: "main" --- # ๐Ÿฆž Lobster [![License: AGPL-3.0-or-later](https://img.shields.io/badge/License-AGPL%203.0--or--later-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Documentation: CC BY 4.0](https://img.shields.io/badge/Documentation-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![PyPI](https://img.shields.io/pypi/v/lobster-ai.svg)](https://pypi.org/project/lobster-ai/) **Bioinformatics co-pilot to automate redundant omics-related tasks so you can focus on science** --- ## ๐Ÿ“‹ Table of Contents - [What is Lobster AI?](#-what-is-lobster-ai) - Overview and use cases - [Quick Start](#-quick-start) - Install in 3 commands - [LLM Providers](#-llm-providers) - Ollama, Anthropic, AWS Bedrock, Google Gemini - [Features](#-features) - Single-cell, bulk RNA-seq, proteomics, visualization - [Case Studies](#-case-studies) - Real-world examples - [Roadmap](#-roadmap) - 2026 development plans - [Use with Claude Code](#-use-with-claude-code) - IDE integration - [Documentation](#-documentation) - Wiki and guides - [Community & Support](#-community--support) - Get help - [License](#-license) - AGPL-3.0-or-later --- ## โœจ What is Lobster AI? Lobster AI combines specialized AI agents with open-source bioinformatics tools to analyze multi-omics data through natural language. Describe your analysis needs - no coding required. **Perfect for:** - ๐Ÿงฌ Bioinformatics researchers analyzing RNA-seq data - ๐Ÿ’ป Computational biologists seeking intelligent workflows - ๐Ÿ”ฌ Life science teams needing reproducible results - ๐Ÿ“š Students learning modern bioinformatics --- ## โšก Quick Start ```bash # Install Lobster globally uv pip install lobster-ai # Configure (interactive wizard) lobster init # Start analyzing lobster chat ``` **Don't have uv?** Install it: [macOS/Linux](https://astral.sh/uv/install.sh) | [Windows](https://astral.sh/uv/install.ps1) **Alternative installation methods:** See [Complete Installation Guide](https://github.com/the-omics-os/lobster-local/blob/HEAD/README_FULL.md#installation-methods) or [Wiki](https://github.com/the-omics-os/lobster-local/wiki/02-installation) --- ### ๐Ÿ“บ Getting Started
Installation

1๏ธโƒฃ Install in 30 seconds
uv pip install lobster-ai

 Configuration

2๏ธโƒฃ Configure in 1 minute
lobster init
Chat Demo

3๏ธโƒฃ Start analyzing with natural language

--- ## ๐Ÿ—๏ธ Architecture Overview Lobster is a **modular bioinformatics platform** with pluggable execution environments, LLM providers, and integrated data management:
Lobster Architecture
### Component Matrix | Layer | Component | Configuration | Use Case | |-------|-----------|---------------|----------| | **Execution** | Local | Default (no setup) | Privacy-first, offline, cost-sensitive | | | Cloud | `LOBSTER_CLOUD_KEY` | Team collaboration, scaling, managed infrastructure | | **LLM Provider** | Ollama | `ollama pull gpt-oss:20b` | Local-only, unlimited usage, offline | | | Anthropic | `ANTHROPIC_API_KEY` | Best quality, quick start, cloud/local | | | AWS Bedrock | AWS credentials | Enterprise, compliance, high throughput | | | Google Gemini | `GOOGLE_API_KEY` | Long context, multimodal, free tier available | | **Data Sources** | GEO/SRA/ENA | Auto-configured | Transcriptomics datasets | | | PRIDE/MassIVE | Auto-configured | Proteomics datasets | | | PubMed/PMC | `NCBI_API_KEY` (optional) | Literature mining, metadata extraction | | **Data Management** | DataManagerV2 | Auto-configured | Multi-modal data orchestration, provenance tracking | ### Configuration & Deployment Lobster supports four deployment patterns optimized for different use cases: | Pattern | Best For | Key Features | |---------|----------|--------------| | **Local + Ollama** | Privacy, learning, zero cost | Offline, unlimited usage, 100% local | | **Local + Anthropic** | Quality, development | Best accuracy, quick setup, flexible | | **Local + Gemini** | Cost optimization, free tier | Long context, multimodal, free tier available | | **Cloud + Bedrock** | Production, teams | Enterprise SLA, high limits, scalable | **Learn more:** - ๐Ÿ“– [Deployment Patterns Guide](https://github.com/the-omics-os/lobster-local/wiki/03-configuration#deployment-patterns) - Detailed setup for each pattern - ๐Ÿ”„ [Provider Auto-Detection](https://github.com/the-omics-os/lobster-local/wiki/03-configuration#provider-auto-detection) - How Lobster selects providers - โš™๏ธ [Complete Configuration Guide](https://github.com/the-omics-os/lobster-local/wiki/03-configuration) - All configuration options --- ## ๐Ÿงฌ Features | Category | Capabilities | Docs | Status | |----------|--------------|------|--------| | ๐Ÿงฌ **Single-Cell RNA-seq** | QC, Clustering, Annotation, Markers, Trajectories | [Tutorial](https://github.com/the-omics-os/lobster-local/wiki/23-tutorial-single-cell) | โœ… Available | | ๐Ÿ“Š **Bulk RNA-seq** | Differential expression, Complex designs, Formula-based stats | [Tutorial](https://github.com/the-omics-os/lobster-local/wiki/24-tutorial-bulk-rnaseq) | โœ… Available | | ๐Ÿ“š **Literature Mining** | PubMed search, Full-text retrieval, Methods extraction | [Guide](https://github.com/the-omics-os/lobster-local/wiki/37-publication-intelligence-deep-dive) | โœ… Available | | ๐Ÿ—„๏ธ **Dataset Discovery** | GEO, SRA, PRIDE, ENA search and validation | [Guide](https://github.com/the-omics-os/lobster-local/wiki/47-geo-download-improvements-2024-11) | โœ… Available | | ๐Ÿ“ˆ **Visualization** | UMAP, Volcano plots, Heatmaps, Interactive figures | [Examples](https://github.com/the-omics-os/lobster-local/wiki/27-examples-cookbook) | โœ… Available | | ๐Ÿงช **Metadata Assistant** | Cross-dataset harmonization, ID mapping | [Guide](https://github.com/the-omics-os/lobster-local/wiki/47-microbiome-harmonization-workflow) | โญ Premium | | ๐Ÿ”ฌ **Proteomics** | DDA/DIA workflows, Missing values, Normalization | [Tutorial](https://github.com/the-omics-os/lobster-local/wiki/25-tutorial-proteomics) | โญ Premium | [Full documentation โ†’](https://github.com/the-omics-os/lobster-local/wiki) --- ### ๐Ÿ“Š Interactive Dashboard (Alpha)
Dashboard Demo

Real-time analysis monitoring with live updates and visualization

Dashboard for deep-diving into omics anlaysis. ```bash #start with lobster dashboard #or during CLI session with โฏ /dashboard ``` --- ## ๐Ÿ“˜ Case Studies ### ๐Ÿงฌ Single-Cell Analysis Download โ†’ QC โ†’ Cluster โ†’ Annotate in one conversation ```bash โฏ Download GSE109564, perform QC, cluster cells, and find markers โœ“ Downloaded 5,000 cells ร— 20,000 genes โœ“ Quality control: filtered to 4,477 high-quality cells โœ“ Identified 12 distinct clusters โœ“ Generated UMAP visualization with marker genes ``` ### ๐Ÿ“š Literature Mining Find papers, extract methods, discover datasets ```bash โฏ Find papers about CRISPR screens in cancer and extract their GEO datasets Found 47 papers with 23 associated GEO datasets Extracted methods from 12 papers with full-text access Cached metadata for all datasets in workspace ``` ### ๐Ÿ“ˆ Visualization Publication-ready figures with natural language ```bash โฏ Create a UMAP colored by cell type with cluster labels Generated interactive UMAP visualization Saved as: geo_gse109564_umap_celltype.html Also exported as PNG for publications ``` [More examples in our cookbook โ†’](https://github.com/the-omics-os/lobster-local/wiki/27-examples-cookbook) --- ## ๐Ÿ—“๏ธ Roadmap **2026 Development:** - [ ] Custom feature agent (bring your tools/best practices) - [ ] Knowledge graph integration for multi-dataset analysis - [ ] Lobster Cloud compute infrastructure - [ ] Enhanced multi-omics workflows (MuData integration) - [ ] Community-contributed agent marketplace **Submit feature ideas:** [GitHub Discussions](https://github.com/the-omics-os/lobster-local/discussions) --- ## ๐Ÿ”ง Use with Claude Code Lobster integrates with [Claude Code](https://claude.com/claude-code) as an Agent Skill, allowing you to run bioinformatics analyses directly from your development environment. ### Quick Setup ```bash # 1. Install Lobster uv pip install lobster-ai lobster init # 2. Install Lobster Skill for Claude Code curl -fsSL https://raw.githubusercontent.com/the-omics-os/lobster-local/main/claude-skill/SKILL.md \ -o ~/.claude/skills/lobster/SKILL.md --create-dirs # 3. Start Claude Code claude ``` ### Usage Examples Claude Code will automatically invoke Lobster when you mention bioinformatics tasks: ```bash # In Claude Code, just ask naturally: You: "Analyze the single-cell dataset in data/counts.h5ad" Claude: I'll use Lobster to analyze this single-cell dataset... [Invokes: lobster query "analyze data/counts.h5ad..."] You: "Download GSE109564 and run quality control" Claude: I'll use Lobster to download and analyze this dataset... [Invokes: lobster query "download GSE109564 and run QC"] You: "Find papers about CRISPR screens in cancer" Claude: I'll use Lobster to search the literature... [Invokes: lobster query "search pubmed for CRISPR screens cancer"] ``` **What this enables:** - ๐Ÿงฌ Run bioinformatics analyses without leaving your IDE - ๐Ÿ“Š Extract data and generate reports programmatically - ๐Ÿ”„ Combine Lobster with your development workflow - ๐Ÿค– Let Claude handle the complexity of bioinformatics commands [Learn more about Agent Skills โ†’](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) --- ## ๐Ÿ“š Documentation | Resource | Description | |----------|-------------| | [Getting Started](https://github.com/the-omics-os/lobster-local/wiki/01-getting-started) | First-time user guide | | [Installation](https://github.com/the-omics-os/lobster-local/wiki/02-installation) | Detailed installation options | | [Configuration](https://github.com/the-omics-os/lobster-local/wiki/03-configuration) | LLM providers, API keys, settings | | [CLI Commands](https://github.com/the-omics-os/lobster-local/wiki/05-cli-commands) | Interactive command reference | | [Examples Cookbook](https://github.com/the-omics-os/lobster-local/wiki/27-examples-cookbook) | Real-world analysis recipes | | [Troubleshooting](https://github.com/the-omics-os/lobster-local/wiki/28-troubleshooting) | Common issues and solutions | | [FAQ](https://github.com/the-omics-os/lobster-local/wiki/29-faq) | Frequently asked questions | **Full reference:** [README_FULL.md](https://github.com/the-omics-os/lobster-local/blob/HEAD/README_FULL.md) | [Wiki Home](https://github.com/the-omics-os/lobster-local/wiki) --- ## ๐Ÿค Community & Support - **๐Ÿ’ฌ Discussions**: [GitHub Discussions](https://github.com/the-omics-os/lobster-local/discussions) - **๐Ÿ› Bug Reports**: [GitHub Issues](https://github.com/the-omics-os/lobster-local/issues) - **๐Ÿ“ง Email**: [info@omics-os.com](mailto:info@omics-os.com) - **๐ŸŒ Website**: [omics-os.com](https://omics-os.com) - **โญ Premium**: [info@omics-os.com](mailto:info@omics-os.com) for pricing **Contributing**: We welcome contributions! See [CONTRIBUTING.md](https://github.com/the-omics-os/lobster-local/blob/HEAD/CONTRIBUTING.md) for guidelines. --- ## ๐Ÿ“„ License Lobster AI is open source under **[AGPL-3.0-or-later](https://github.com/the-omics-os/lobster-local/tree/HEAD/LICENSE)**. This license ensures all users receive the freedoms to use, study, share, and modify the software. Documentation is licensed **CC-BY-4.0**. **Commercial licensing:** Contact [info@omics-os.com](mailto:info@omics-os.com) ---
**Transform Your Bioinformatics Research Today** `uv pip install lobster-ai && lobster chat` *Made with sleep deprivation โ˜•๏ธ by [Omics-OS](https://omics-os.com)*