Overview

The Lightcone Research Stack is Lightcone Research's tooling for research analyses described with ASTRA (Agentic Schema for Transparent Research Analysis).

Your AI agent can write and run an analysis faster than you can check it, yet before you publish the result you need to know which choices went into it, and to be able to run it again when a referee asks. The Lightcone Research Stack keeps that record for you, as an ASTRA description of the analysis. Before writing any code, the agent works through the plan with you: you make the scientific choices, and it records each one with the evidence behind it. Every result then comes from a recorded run, so you or a collaborator can trace a figure back to the decisions that shaped it and reproduce it months later.

The Lightcone Research Stack works with Claude Code and Codex, on your own code and data.

Add the Lightcone plugin to your agent:

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

Then follow the Quick Start to set up your first analysis.

Elements of the stackCopy Anchor Link

How it worksCopy Anchor Link

The stack is a set of separate tools that work on one repository: the project's own git repository, whose astra.yaml describes the analysis in ASTRA. The Lightcone CLI reads that file to run the analysis and commits each result next to it, with a record of how it was made. Lightcone Lab, MySTRA and the Agent Skills read the same file and the same record. They share nothing else, so you can use, replace or leave out any of them on its own.

We split the stack up this way so that it can attach to a project that already exists. A research group has its own code, its own compute and its own way of writing papers, and it rarely wants to move all of that into a new system at once. With separate tools, you can start by writing the specification with your agent and running it with the CLI, and add Lab or MySTRA later, or not at all. The specification is plain YAML with an open schema, so a tool we didn't write, including one you write yourself, can read it too.

You and your agent

Agent Skills teach Claude Code or Codex to write the specification with you and run it.

Drives the CLI

Lightcone CLI

Runs each recipe from the specification in a sandbox, and commits the result with certified provenance: the code, inputs and environment that produced it.

Code and artifact versioninggit holds the code and the specification. git-annex holds the data and results, each output with a content-addressed run record.

Reusable environmentA uv lockfile, which you can wrap in a container image. The CLI hashes it into each output's record.

Runs recipes

Compute

From a laptop to a clusterRun recipes on your laptop or on a Dask, Kubernetes or Slurm cluster, with the same run record.

Reads the specRecords results

Your project · one git repository

astra.yaml

Copy Text

decisions:
  noise_model:
    rationale: sets the error budget
    options:
      gaussian: {insights: [gaussian_noise]}
      heavy_tailed: {excluded: true}
outputs:
  - id: fit_results
    decisions: [noise_model]
    recipe:
      command: python src/fit.py {decisions.noise_model}

The analysis as structured data: insights from the literature, decisions with their rationale and the options not taken, recipes that make each output, and the findings the outputs support.

index.md

Copy Text

Using {astra}`decisions.noise_model`,
we obtain the following fit.

:::{astra} outputs.fit_results
:::

Your write-up in MyST. You link decisions to their record and embed results from the project, and MySTRA resolves both when you build the document.

src/

Your code, in git. A recipe names the command that runs it.

data/

Input data, carried by git-annex.

results/

Your results, each with a manifest and run record.

Reads the spec and results

Lightcone Lab

A JupyterLab workbench that shows the project: its results, decisions and cited papers, and the run behind each result. Start Claude Code or Codex from the project's Home.