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 --version0.2.9Check 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 statusClaude 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-pipelineConnect 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 --forceClaude 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.jsonConnect 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 --forceOpenAI 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 --forceGoogle 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 starterCheck 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.cspvalidRun 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.cspWrite a report
Write a report of the saved session as Markdown.
cohortdag report survival.csp --out report --format mdWrote study report (4 file(s)) to reportRead 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.cspData 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.cspCheck 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 --strictno findingsFrom the window, Help > Connect AI Agents… does the same as cohortdag agent install, one agent at a time.