Prelaunch preview. Explore AROS products and skills. Checkout is in sandbox; no real payment.
← CohortDAG documentation

Use CohortDAG from an AI agent or the command line

How-to · CohortDAG 0.2.9

CohortDAG ships a command-line tool, cohortdag, and an MCP server, cohortdag-mcp, that drive the same compiler and Spark backend as the window. An AI agent such as Claude Code, Codex or Google Antigravity uses them to author, check and run pipelines; adding steps to a window you have open needs your acceptance in the window. CohortDAG itself contains no AI model; the agent runs outside the app and drives it through these tools. Every command below was run on a clean Ubuntu 24.04 machine with the 0.2.4 package installed as in Get started; the output shown is what it printed.

Commands

Check the command

The package puts cohortdag and cohortdag-mcp on your PATH. Print the version to check.

cohortdag --version
0.2.9

Check the environment

Check Python, Java, PySpark and the backend. The doctor starts a real Spark driver, so it takes a moment.

cohortdag doctor
✓ Node.js: v24.22.2 (running this CLI)
  ✓ Python: Python 3.12.3 (/home/researcher/.config/cohortdag/python-env/bin/python -> /home/researcher/.config/cohortdag/python-env/bin/python)
  ✓ Java (JVM): openjdk version "17.0.21.0.3" 2026-10-24 (PATH)
  ✓ analysis packages (pyspark + production chain): pyspark 3.5.9; all required imports loaded
  ✓ backend (server.py): /opt/CohortDAG/resources/src/python/server.py
  ✓ Spark driver boot: a real SparkSession started and stopped
  ! data root: $COHORTDAG_DATA_ROOT not set
      fix: Set $COHORTDAG_DATA_ROOT to the directory holding your source parquet tables (only needed to run pipelines that read them).

Environment OK — the CohortDAG backend can run.

See which agents CohortDAG can connect to

CohortDAG can register itself with Claude Code, Codex (which also serves the ChatGPT desktop app) and Google Antigravity. This lists, for each agent, which CohortDAG entries are present or absent. In the output below every entry is absent, because no agent is set up on this machine yet; run it again after you connect one. Running cohortdag agent install --target all installs the skill and registers the server for all three agents in one step; restart each agent afterwards. The window's Help > Connect AI Agents… does the same, one agent at a time.

cohortdag agent status
Claude Code: not detected (/home/researcher/.claude)
  claude-skill         absent     /home/researcher/.claude/skills/cohortdag-pipeline
  claude-mcp-plugin    absent     /home/researcher/.claude/skills/cohortdag
Google Antigravity: not detected (/home/researcher/.gemini/config)
  antigravity-plugin   absent     /home/researcher/.gemini/config/plugins/cohortdag
OpenAI Codex: not detected (/home/researcher/.codex)
  codex-skill          absent     /home/researcher/.codex/skills/cohortdag-pipeline

Connect Claude Code

Without --dry-run and --force, this command installs the cohortdag-pipeline skill and registers the CohortDAG MCP server. The output below comes from --dry-run, which lists what would be written (6 files) and changes nothing; run the command without those two options to install. Restart Claude Code, type /cohortdag-pipeline in its chat window and ask in your own words, for example: Use CohortDAG to build the starter survival pipeline and run it on Spark. The agent authors a pipeline file, checks it and runs it with CohortDAG's own compiler and Spark backend; Spark needs Java and pyspark, and cohortdag doctor checks Node, Python, Java and pyspark. Adding steps to a window you already have open needs your acceptance in a dialog that lists them, and you can decline.

cohortdag agent install --target claude-code --dry-run --force
Claude Code — would write 6 file(s):
  /home/researcher/.claude/skills/cohortdag-pipeline/SKILL.md
  /home/researcher/.claude/skills/cohortdag-pipeline/examples/minimal.csp
  /home/researcher/.claude/skills/cohortdag-pipeline/.cohortdag-managed.json
  /home/researcher/.claude/skills/cohortdag/.claude-plugin/plugin.json
  /home/researcher/.claude/skills/cohortdag/.mcp.json
  /home/researcher/.claude/skills/cohortdag/.cohortdag-managed.json

Connect Codex or the ChatGPT desktop app

This installs the skill under ~/.codex and registers the cohortdag server in ~/.codex/config.toml; the same install serves the Codex command-line tool and the ChatGPT desktop app. Restart whichever you use (Codex or the ChatGPT desktop app), invoke the skill by typing @cohortdag-pipeline in ChatGPT or through /skills in the Codex command-line tool, and ask for the analysis as above. The ChatGPT website runs in a browser and cannot reach a program on your computer, so it cannot use CohortDAG.

cohortdag agent install --target codex --dry-run --force
OpenAI Codex — would write 4 file(s):
  /home/researcher/.codex/skills/cohortdag-pipeline/SKILL.md
  /home/researcher/.codex/skills/cohortdag-pipeline/examples/minimal.csp
  /home/researcher/.codex/skills/cohortdag-pipeline/.cohortdag-managed.json
  /home/researcher/.codex/config.toml [key mcp_servers.cohortdag]

Connect Google Antigravity

This installs a plugin under ~/.gemini/config/plugins/cohortdag, with the skill inside it, and registers the cohortdag server in ~/.gemini/config/mcp_config.json. Restart Antigravity; the plugin appears under Settings → Customizations. Then ask for the analysis as above.

cohortdag agent install --target antigravity --dry-run --force
Google Antigravity — would write 5 file(s):
  /home/researcher/.gemini/config/plugins/cohortdag/plugin.json
  /home/researcher/.gemini/config/plugins/cohortdag/skills/cohortdag-pipeline/SKILL.md
  /home/researcher/.gemini/config/plugins/cohortdag/skills/cohortdag-pipeline/examples/minimal.csp
  /home/researcher/.gemini/config/plugins/cohortdag/.cohortdag-managed.json
  /home/researcher/.gemini/config/mcp_config.json [key mcpServers.cohortdag]

List the starter pipelines

List the pipelines an agent can start from.

cohortdag pipelines list --kind starter

Check a pipeline

Run the structural checks on a pipeline file before running it. Here, the bundled survival starter.

cohortdag validate /opt/CohortDAG/resources/resources/templates/starter-survival.csp
valid

Run it on Spark

Run every output on Apache Spark and save the session, with its results, to a new .csp file that the window can open.

cohortdag run /opt/CohortDAG/resources/resources/templates/starter-survival.csp --all-outputs --save-session survival.csp

Write a report

Write a report of the saved session as Markdown.

cohortdag report survival.csp --out report --format md
Wrote study report (4 file(s)) to report

Read a pipeline by its parts

Print a pipeline as phases and the groups inside them. Here, the bundled Bello-Chavolla study.

cohortdag outline /opt/CohortDAG/resources/resources/templates/study-bello-chavolla-2020-mexico-cox.csp
Data sources (0 groups, 1 node)
Cohort definition (1 group, 3 nodes)
  Keep confirmed SARS-CoV-2 cases — 3 nodes: Recodes covariates and follow-up, keeps RESULTADO = 1; writes `bello_chavolla_confirmed_cohort`.
Descriptive results (2 groups, 4 nodes)
  Confirmed cohort mortality (n = 51,633) — 2 nodes: Reads the confirmed cohort back; reproduces Table 1 (5,332 deaths).
  Training cohort, 80% split (n = 41,307) — 2 nodes: Random 80% split stratified by mortality, as in the paper (seed 123).
Analysis (2 groups, 6 nodes)
  Survival by diabetes status — 2 nodes: Kaplan-Meier curves for known diabetes status; reproduces Figure 2.
  Table 2 Cox models — 4 nodes: Individual variables, the lethality score and its risk categories; reproduces Table 2.

Suggest groups for a pipeline

Print a suggested grouping as JSON, without changing the file. Rename the groups by what they do, then save them with cohortdag groups apply.

cohortdag groups propose /opt/CohortDAG/resources/resources/templates/starter-survival.csp

Check that groups read well

Check a pipeline's groups for names, sizes and descriptions. Each finding comes with a fix. The bundled studies have no findings.

cohortdag groups lint /opt/CohortDAG/resources/resources/templates/study-bello-chavolla-2020-mexico-cox.csp --strict
no findings

From the window, Help > Connect AI Agents… does the same as cohortdag agent install, one agent at a time.