Install

Prerequisites

Install these before running scripts/install.sh — the script registers cosmoTRON into both, it does not install either one:

• opencode — the agent runtime that drives @cosmotron.
• Ollama (docs) — if you're running local open-weights models (see Configuration). Not needed if you only drive the pipeline via Claude Code or direct Python calls.

One-shot installer (recommended)

scripts/install.sh

The script is idempotent and:

1. optionally creates the cosmotron environment for you — prompts for a tool (conda / mamba / uv / skip) and an env name, then runs <tool> env create -f environment.yaml (conda/mamba) or uv venv (pip/venv only — no conda-forge, see the note below) and activates it for the rest of the run;
2. pip install -e ".[all]" (core + covariance + readers + review extras) — skipped automatically when step 0 already installed everything via environment.yaml;
3. registers the cosmotron MCP server in ~/.config/opencode/opencode.json;
4. optionally registers it for Claude Code (a project .mcp.json);
5. optionally installs the agents + skills globally (symlinks into ~/.config/opencode/agents/ and …/skills/) so @cosmotron works from any directory — otherwise it stays folder-scoped to this repo;
6. optionally fixes local-model sampling parameters (see Configuration);
7. optionally adds a cosmotron shell alias (alias cosmotron='opencode --agent cosmotron') to your shell rc file.

Flags: --yes (non-interactive), --global / --no-global, --no-claude, --no-pip, --no-ollama-fix, --no-alias, --env-tool=conda|mamba|uv|skip, --env-name=NAME, --no-env-create. Run scripts/install.sh --help for the full list.

Prefer to create the environment yourself first? conda env create -f environment.yaml && conda activate cosmotron && scripts/install.sh — the script detects the active env and skips straight past step 0.

Why conda-forge, and why uv can't fully replace it

pymaster (NaMaster) ships source-only on PyPI — no wheels — so a plain pip install compiles it from source and needs cfitsio/gsl/ fftw already on your system. cosmosis and lsstdesc-crow (the inference stack) have no pip path at all. conda-forge ships prebuilt binaries for all of these and pulls their C-library dependencies automatically — environment.yaml uses it for exactly that reason. uv is pip/venv-only (no conda-forge access), so a uv-created environment gets the pipeline + covariance stack but not inference.

MCP server only (manual pip install)

Skips everything else scripts/install.sh does — no environment creation, no opencode/Claude Code registration, no global symlinks, no shell alias, no Ollama sampling fix. Just the Python package:

pip install -e .                 # core
pip install -e ".[all]"          # core + covariance + readers + review (pip-able extras)
pip install -e ".[covariance]"   # just Gaussian covariance (sacc, pyccl, tjpcov)
pip install -e ".[inference]"    # firecrown + getdist (see caveat below)
pip install -e ".[docs]"         # this documentation site (mkdocs + mkdocs-material + mkdocstrings)

Extra	Pulls	For
covariance	sacc, pyccl, tjpcov	Gaussian covariance
readers	h5py, pandas	HDF5 / CSV catalogue ingest
review	pillow	PNG embedding in review evidence
inference	firecrown, getdist	Firecrown likelihood + posterior plots
docs	mkdocs, mkdocs-material, mkdocstrings[python]	Building this site
all	the pip-able sets above (not inference, not docs)	convenience

Requires Python ≥ 3.11. Core deps: fastmcp, pydantic, pyyaml, numpy, scipy, astropy, healpy, pymaster, matplotlib. The covariance / readers / review / inference deps are imported lazily, so the server boots without them — only the corresponding tool needs them.

healpy/pymaster via bare pip

pymaster has no PyPI wheels (source-only) and healpy benefits from the same prebuilt binaries — a bare pip install here compiles from source and needs cfitsio/gsl/fftw already present. Use environment.yaml (see One-shot installer) instead unless you already have those system libraries set up.

Inference is conda-forge, not pip

firecrown + getdist are pip-able, but the full inference run needs cosmosis and lsstdesc-crow, which are conda-forge only:

conda install -c conda-forge firecrown cosmosis lsstdesc-crow

The package installs a cosmotron-mcp entry point (stdio transport).

Registering the MCP server manually

opencode

opencode mcp add
#   type:    local
#   command: $(which cosmotron-mcp)      # e.g. ~/miniforge3/envs/cosmotron/bin/cosmotron-mcp

or add the block directly to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "cosmotron": {
      "type": "local",
      "command": ["/path/to/envs/cosmotron/bin/cosmotron-mcp"],
      "enabled": true
    }
  }
}

Claude Code

Project-scoped (.mcp.json in repo root, gitignored — each clone needs its own registration):

{
  "mcpServers": {
    "cosmotron": {
      "type": "stdio",
      "command": "/home/you/miniforge3/envs/cosmotron/bin/cosmotron-mcp"
    }
  }
}

User-scoped (works from any project):

claude mcp add cosmotron $(conda run -n cosmotron which cosmotron-mcp)

The cosmotron shell alias

scripts/install.sh's alias step adds:

alias cosmotron='opencode --agent cosmotron'

to ~/.zshrc or ~/.bashrc (detected from $SHELL), guarded by an idempotency marker so re-running the installer never duplicates it. Skip it with --no-alias, or add it yourself if you'd rather not run the installer's prompt.