pi-snakemake

A pi coding agent extension for working with Snakemake workflows.

Overview

This extension integrates Snakemake pipeline management directly into the pi agent workflow. It provides tools for inspecting, running, and managing Snakemake pipelines — all through natural language interaction.

Features

Tools

Tool	Description
snakemake_dag	Visualize and inspect the pipeline DAG. Shows rule dependencies, target files, and the execution graph.
snakemake_status	Check pipeline status — what's up-to-date, what's out of date, what would run.
snakemake_run	Execute the workflow with configurable options (cores, force, dry-run, etc.). Streams output in real-time.
snakemake_rule	Inspect a specific rule's inputs, outputs, parameters, resources, and conda environment.
snakemake_clean	Clean workflow artifacts. Selective or full cleanup with safety confirmation.
snakemake_report	Generate a Snakemake HTML report of the workflow execution.

Commands

Command	Description
/snakemake	Open an interactive dashboard showing DAG summary, pending rules, and last run status.

Auto-Detection

• Automatically detects Snakefile in the current directory or parent directories
• Injects Snakemake-aware context into the system prompt when a pipeline is detected
• Suggests relevant tools when working with pipeline files

Usage

snakemake_dag — Visualize the Pipeline DAG

The snakemake_dag tool parses Snakemake's DOT-format DAG output and presents it in three complementary views:

1. Summary — one-line-per-rule grouping with target markers

DAG: 12 nodes, 5 rules
Targets: results/final.bam

  trim_reads
    - results/trimmed/R1.fastq
    - results/trimmed/R2.fastq
  map_reads
    - results/mapped/R1.bam
    - results/mapped/R2.bam
  call_variants ★
    - results/variants/calls.vcf

2. Dependency Tree — shows what a target depends on (upstream)

└── [call_variants] results/variants/calls.vcf
    ├── [map_reads] results/mapped/R1.bam
    │   └── [trim_reads] results/trimmed/R1.fastq
    └── [map_reads] results/mapped/R2.bam
        └── [trim_reads] results/trimmed/R2.fastq

3. Execution Tree — shows the full execution order from root files

├── [trim_reads] results/trimmed/R1.fastq
│   └── [map_reads] results/mapped/R1.bam
│       └── [call_variants] results/variants/calls.vcf
└── [trim_reads] results/trimmed/R2.fastq
    └── [map_reads] results/mapped/R2.bam
        └── [call_variants] results/variants/calls.vcf

Example usage:

> Show me the DAG for the final.bam target
> What does call_variants depend on?
> List all rules in the pipeline

The tool auto-detects the Snakefile, or you can pass it explicitly:

> Show DAG with snakefile=/path/to/Snakefile

DAG Cache — When snakemake can't run (e.g., sandbox restrictions, missing files), the extension automatically falls back to a pre-generated DAG:

1. Generate the DAG once outside the sandbox (or with full access):

   mkdir -p .snakemake
   snakemake --dag > .snakemake/dag.dot

2. The extension will try snakemake --dag first, and if it fails, automatically falls back to .snakemake/dag.dot, displaying:

   > ⚠️ DAG from cache (generated 7/14/2026, 10:30:00 AM)
   

3. To refresh the cache, regenerate the file:

   rm .snakemake/dag.dot
   snakemake --dag > .snakemake/dag.dot

snakemake_status — Check Pipeline Status

Shows which files are up-to-date, out-of-date, missing, or unused.

> What's out of date in the pipeline?
> Which files need to be re-run?

snakemake_run — Execute the Workflow

Runs the Snakemake pipeline with safety defaults (dry-run mode by default).

> Run the pipeline with 8 cores
> Dry-run the pipeline to see what would happen
> Force re-run of the mapping step

snakemake_rule — Inspect a Rule

Shows inputs, outputs, parameters, resources, and conda environment for a specific rule.

> What are the inputs to the map_reads rule?
> Show me the conda environment for trim_reads

snakemake_clean — Clean Artifacts

Selective or full cleanup with safety confirmation.

> Clean all intermediate files
> Remove results/trimmed/

snakemake_report — Generate HTML Report

Creates a Snakemake HTML execution report.

> Generate a report of the last run

/snakemake — Browser and terminal dashboards

Opens an interactive dashboard showing the DAG, pending rules, workflow controls, current source provenance, file/run provenance, and recent executions. The browser and terminal TUI use the same services and labels; the TUI uses compact layouts and detail views where terminal space is limited.

> /snakemake

Selecting a rule loads its source provenance lazily: Snakefile line range, literal script:, notebook:, and wrapper: references, available Git/JJ state, and optional JJ session checkpoint metadata. Missing Git or JJ, unsupported metadata, command failures, and partial results are shown as truthful unavailable/partial states and do not prevent the extension or the rest of the dashboard from working.

The workflow controls default to a dry-run. A live run shows its exact target and options and requires explicit confirmation. Cleanup is a two-step action: first preview what Snakemake would remove, then explicitly confirm that exact cleanup. Opening, refreshing, navigating, or inspecting history never starts a live run or cleanup. Browser and TUI actions call the same services and have the same command semantics as snakemake_run and snakemake_clean; they do not introduce separate execution paths.

Provenance model

The dashboard deliberately separates two kinds of information:

• Current source provenance describes the Git/JJ state observed now. It can differ from the state used by an older execution.
• Captured execution provenance is a bounded snapshot attempted around a live run. It contains the run ID, command options, result, available Git/JJ identifiers, warnings, and before/after observations for explicit targets.

Target observations show that a file was missing, present, or changed around a run. They are not causal proof that the run produced that file. Likewise, related executions are inferred only when the selected rule's explicit output matches a recorded explicit target; DAG ancestry and incidental files do not create a relationship.

Only non-dry live runs attempt a durable record. Successful runs, failures, timeouts, aborts, and spawn failures can be recorded; dry-runs never enter the ledger. Capture and persistence are best-effort, so a run may have partial provider data or warnings without changing its Snakemake result. Legacy last-run session entries without a runId remain displayable but have no durable detail record.

Execution JSON is stored outside the workflow under Pi's agent state root:

<Pi agent state>/pi-snakemake/execution-records/<workflow-path-hash>/<run-id>.json

The path hash separates workflows without writing into the workflow, .snakemake, .git, or .jj. Files are private, bounded to 256 KB, and the newest 100 records per workflow are retained by default. The external ledger may be archived or removed independently; removing it does not remove workflow outputs, while missing records appear as unavailable history.

Architecture

├── index.ts          # Extension wiring: events, tools, and commands
├── environment.ts    # Project discovery and Snakemake command selection
├── rules.ts          # Rule, status, and run-output parsing
├── provenance.ts     # Optional Git/JJ source provenance collection
├── execution-provenance.ts # External durable execution records
├── execution-read-model.ts # Shared browser/TUI execution presentation
├── snakemake-run-service.ts # Single run orchestration path
├── snakemake-clean-service.ts # Shared preview/confirmed cleanup
├── dag.ts            # Cached Graphviz DAG loading
├── dashboard-data.ts # Serializable dashboard data collection
├── ui.ts             # Interactive terminal dashboard
├── types.ts          # Shared domain types
└── tests/            # Parser and environment unit tests

Design Decisions

• Safety first: snakemake_run defaults to --dryrun mode. Real execution requires explicit confirmation.
• State persistence: Last-run summaries use session entries; durable live-run records use external Pi-managed state.
• Local development dependencies: The extension uses TypeScript plus local Pi host, React, Vite, and Vitest packages for validation.
• Conservative provenance: Current Git/JJ state, captured run state, and observed files remain distinct claims.

Installation

Place this extension in one of these locations for auto-discovery:

# Global (all projects)
cp -r . ~/.pi/agent/extensions/pi-snakemake

# Project-local
cp -r . .pi/extensions/pi-snakemake

Or load directly:

pi --extension .

Requirements

• Snakemake installed and available in $PATH
• A Snakefile in the project directory (or parent)
• Optional: Git for commit and dirty-state provenance
• Optional: JJ 0.43.0 or compatible jj CLI on $PATH for JJ provenance

Git and JJ are independent optional providers. With only one installed, that provider is shown and the other is marked unavailable; with neither, the UI shows an explicit no-VCS state. Neither is required for extension startup.

For development in this sandbox, Snakemake can be run without a project-local virtualenv via:

uv run --python 3.12 --with snakemake snakemake

Useful validation commands:

npm run test:all
npm run typecheck:all
npm run build:web
npm run test:e2e
npm run test:visual
npm run package:check

Playwright is a local development dependency; install its browser once with npx playwright install chromium. See CONTRIBUTING.md for the validation/compatibility matrix, visual baseline workflow, CI behavior, and release packaging rules.