Skip to content

Welcome to the user guide

lightcone-cli is a small toolchain that turns a research question into a reproducible analysis. You describe what you're trying to learn, a cli agent helps you turn that into a precise specification, and the lc command line keeps the resulting code, decisions, and outputs in sync thanks to the ASTRA specification.

No need to write code by hand, you stay in charge of the scientific choices, the agent handles the implementation.

What this guide covers

  • Install — get the lc command line and Claude Code running on your machine or on a cluster.
  • Getting Started — create your first project, run it end-to-end, and understand what each piece does.
  • The Agentic Workflow — /lc-new, /lc-from-code, /lc-from-paper, and /lc-feedback — what each command does and when to reach for it.
  • Running on a Cluster — taking your analysis to a SLURM HPC system, including Perlmutter-specific notes.
  • Troubleshooting — common issues and how to unstick them.
  • Glossary — the terms that show up everywhere (universe, decision, manifest, …) explained in plain language.

What you'll do, in three lines

Quick start

uv tool install lightcone-cli
lc init my-analysis && cd my-analysis
claude
# then, inside Claude Code,  run /lc-new

pip install lightcone-cli
lc init my-analysis && cd my-analysis
claude
# then, inside Claude Code: /lc-new

That's the shortest possible path. The rest of the guide is the unhurried version.

What lightcone-cli is not

  • A statistics package. It runs your code; it doesn't compute things itself.
  • A workflow language. Recipes in astra.yaml are short shell or Python commands, not a DSL. There's no learning curve beyond what's in Getting Started.
  • An IDE. lc is a command-line tool; the agent surface lives inside the agent harness (Claude Code for now).

If you'd rather skim the design and architecture, the maintainer docs are the other half of this site.