OmicsClaw AGENTS.md

AGENTS.md — OmicsClaw Guide for AI Coding Agents

This guide is for AI coding agents working on the OmicsClaw codebase.

Repository Working Contract

Before any complex repository maintenance, feature, or refactor task, read README.md first for project context and prior decisions. Then read this AGENTS.md, root SPEC.md, and the directly relevant code/docs.

Core rules:

• Reply in the user's language, usually Chinese or English.
• Stay concise, practical, and execution-focused.
• For non-trivial changes, work from a concise plan, keep edits scoped, and verify claims with concrete commands or file inspections before reporting completion.
• When you make an important decision or complete a meaningful milestone, update README.md while preserving its existing structure.

Project Overview

OmicsClaw is a multi-omics analysis platform supporting 95 registered skills across 8 domains: spatial transcriptomics, single-cell omics, genomics, proteomics, metabolomics, Bulk RNA-seq, orchestration, and literature. Each skill is a self-contained module that performs a specific analysis task via CLI or Python API. All processing is local-first. Design is inspired by ClawBio.

Note: OmicsClaw evolved from SpatialClaw and now uses a unified omicsclaw.py entrypoint.

Setup

cd /path/to/OmicsClaw

# Recommended: full conda-primary install (R + CLIs + Python in one shot)
bash 0_setup_env.sh
conda activate OmicsClaw

# Lightweight alternative (Python-only skills, no R or external CLIs):
# pip install -e .
# pip install -e ".[interactive]" / ".[tui]" / ".[memory]" / ".[channels]" / ".[full]"

python omicsclaw.py list   # or: oc list
python omicsclaw.py run spatial-preprocess --demo

oc short alias: After installing OmicsClaw (either path), both omicsclaw and oc commands are available system-wide via the [project.scripts] entry in pyproject.toml.

Dependency source of truth:

• Python deps live in pyproject.toml (used by both install paths).
• R packages, bioinformatics CLIs, build toolchain live in environment.yml (conda path only).
• GitHub-only R packages are installed inline by 0_setup_env.sh Tier 3 (devtools::install_github for spacexr, CARD, CellChat, numbat, SPARK, DoubletFinder).
• Optional analysis backends (cellrank, palantir, scvelo, tangram-sc, …) are catalogued per domain in skills/<domain>/_lib/dependency_manager.py DEPENDENCY_REGISTRY (canonical PyPI name → module + install_cmd). This is the SSOT for backend name mapping; new algorithms register here.
• Per-skill requires: frontmatter is generated/checked from the real import surface by scripts/audit_skill_requires.py (--check in CI, --write to regenerate). Never hand-edit it to "fix" a missing backend — register the backend and run --write. See CONTRIBUTING.md.

The repository does not use a root requirements.txt as a primary install entrypoint.

Known pip check warning: the full conda environment keeps jinja2>=3.1.5 for FastAPI/nbconvert even though upstream pygpcca==1.0.4 still pins jinja2==3.0.3. Treat that single warning as metadata noise when oc doctor and targeted import checks pass.