Install¶

To get started on a lightcone project, you need three things on your machine: Python 3.11+, the lightcone command line tool lc, and an agent CLI (supporting Claude Code, Codex, and opencode).
A container runtime is optional but recommended.

1. Python¶

If you don't already have a recent Python

brew install python@3.12

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

module load python      # NERSC Python (3.11+)

conda create -n your-env-name python=3.11 -y
conda activate your-env-name

conda deactivate
mv ~/.conda/envs/your-env-name $SCRATCH/conda-envs/
ln -s $SCRATCH/conda-envs/your-env-name ~/.conda/envs/your-env-name

curl -LsSf https://astral.sh/uv/install.sh | sh

uv python install 3.12

2. lightcone-cli¶

The published name on PyPI is lightcone-cli; the command it provides is lc.

uv tool install lightcone-cli

python -m pip install lightcone-cli

uv tool install lightcone-cli

# NERSC python module
module load python
python -m pip install --user lightcone-cli   # lands in ~/.local/bin/

# Conda env
conda activate your-env-name
python -m pip install lightcone-cli

git clone https://github.com/LightconeResearch/lightcone-cli.git
uv pip install -e ./lightcone-cli

git clone https://github.com/LightconeResearch/ASTRA.git
uv pip install -e ./ASTRA

Get a confirmation of the proper installation by running

lc --version                # → lightcone-cli, version ...

This install puts two global commands on PATH: lc and astra. Both ship from the one lightcone-cli wheel (astra-tools is a dependency), so a single install exposes both — no project venv, no version skew between them. lc init does create a project .venv, but leaves it empty: neither lc nor astra goes in it. It's the analysis environment your agent populates as the project's dependencies come into focus; requirements.txt feeds the container build, not this venv. When a project needs a spec-exact astra, invoke it per-call with uvx --from astra-tools==X --with astra-spec==Y astra.

Note Some people may have already set a personal shell alias lc='ls --color'. If that's you, installing lightcone-cli will shadow the alias — make sure to rebind it (e.g. alias l='ls --color').

3. Global configuration¶

~/.lightcone/config.yaml is created automatically the first time you run any lc command. No manual setup step is needed. The file starts as:

container:
  runtime: auto

auto detects whichever of podman, docker, or podman-hpc is on your PATH (and skips docker if its daemon isn't running). Feel free to pin the runtime later by editing this file directly.

4. Agentic CLI¶

Most of your interactions with a lightcone project happen through an agent-based CLI. Any agent that can drive a project shell works — the choice is yours.

curl -fsSL https://claude.ai/install.sh | bash

claude --version
claude        # first run prompts for login (claude.ai or API key)

curl -fsSL https://opencode.ai/install | bash

4b. Install the lightcone skills¶

The lc slash commands (/lightcone:new, /lightcone:report, and the rest) ship as a plugin, not with the lightcone-cli package. lc init registers the agent-skills marketplace globally with each harness, then activates the plugin per project, so normally you do nothing here. The by-hand commands below are the fallback if you skipped lc init or want to register a harness yourself.

claude plugin marketplace add LightconeResearch/agent-skills
claude plugin install lightcone@lightcone-research

codex plugin marketplace add LightconeResearch/agent-skills
codex plugin add lightcone@lightcone-research

The skills live in LightconeResearch/agent-skills. See Skills for the full plugin and command map.

Open a project in your terminal or editor (see Getting Started) and run your agent CLI from inside it. Your agent exposes these as slash commands like /lightcone:new, /lightcone-experimental:from-code, and /lightcone-experimental:from-paper — see The Agentic Workflow.

5. (Optional) Docker or Podman¶

If your analysis declares a container: (which it usually should — it makes the result reproducible across machines), you need a container runtime:

• Local laptop: install Podman (rootless, no daemon) or Docker.
• HPC login node: see Running on a Cluster.

The auto mode picks whichever container runtime you have. If you don't have either, you can still use lc — set runtime: none in ~/.lightcone/config.yaml and recipes will run on the host without isolation.

With runtime: none, recipes use whatever is on your PATH. lc does not provision an environment for them. Install the packages from requirements.txt into the project .venv yourself — uv pip install --python .venv/bin/python -r requirements.txt, then activate it before lc run (or use any environment manager you prefer). With a container runtime this is unnecessary: the image installs requirements.txt at build time.

Sanity check¶

lc --help
lc init --help

Both should print help text. If lc is shadowed by an ls alias, unset it (unalias lc) or use the full path ($(which lc) --version).

Updating¶

uv tool upgrade lightcone-cli

pip install -U lightcone-cli astra-tools

cd path/to/lightcone-cli
git pull
uv pip install -e .        # only needed if pyproject.toml changed

Uninstalling¶

uv tool uninstall lightcone-cli

pip uninstall lightcone-cli