Skip to content

Getting Started

This page walks you from "nothing on my disk" to a project that's ready for the agent to fill in. The actual doing science part is in the tutorial; this page is the orientation.

Make sure you've finished the install first.

1. Create a project

lc init my-analysis
cd my-analysis

lc init is a one-shot setup. It creates a small, opinionated directory layout and stops; it doesn't ask any questions.

2. What you got

my-analysis/
├── astra.yaml                  # the spec — this is where everything lives
├── CLAUDE.md                   # short note for the agent (resumes context across sessions)
├── .gitignore
├── .venv/                      # Python virtual env (skip with --no-venv)
├── .lightcone/                 # internal scratchpad — don't edit by hand
├── .claude/                    # Claude Code plugin — skills, agents, hooks
├── universes/                  # placeholder for now
└── results/                    # placeholder for now

The two files you'll actually look at:

astra.yaml

The single source of truth for your analysis. Inputs, outputs, methodological decisions, recipes. Everything else lightcone-cli does is downstream of this file.

The boilerplate written by lc init is one example output and an empty decisions block — enough to run an lc run and see something materialize, but not yet a real analysis.

CLAUDE.md

A short note that tells Claude Code about the project. The skills will update this as you go (filling in working notes, design context). You can edit it by hand whenever you want.

3. Open Claude Code

claude

That opens an interactive session inside my-analysis/. Claude Code reads astra.yaml and CLAUDE.md so it has context.

4. The five slash commands

Inside Claude Code:

Command Use it when…
/lc-new You're starting from a research question and an empty astra.yaml.
/lc-build You have a scoped astra.yaml and you want the analysis implemented and run.
/lc-verify You finished a build and want a read-only audit.
/lc-migrate You have an existing codebase you want wrapped in ASTRA.
/lc-feedback Something broke and you want to file a GitHub issue without leaving the session.

The next page, The Claude Code Workflow, explains each of these in more detail.

5. The four CLI commands you'll actually type

You can mostly stay inside Claude Code, but the durable workhorse is the lc CLI. The four commands you'll touch by hand:

lc run                          # produce all outputs declared in astra.yaml
lc status                       # what's done, stale, or missing — fast and offline
lc verify                       # heavier audit: recomputes hashes, walks the input chain
lc build                        # build container images declared in astra.yaml

Each of these has a one-page reference in the CLI section of the maintainer docs if you want exact flags.

6. Read on