drun automation language (with AI support)

drun is a semantic task automation language for readable project workflows, with AI skills support.

xdrun is the CLI that executes .drun task files. It is designed for automation that reads closer to intent than shell glue, while still running the commands your project needs.

Full documentation lives at phillarmonic.github.io/drun, including the AI integration guide.

Official editor extensions are available for VS Code, Open VSX, and JetBrains IDEs.

Why drun?

• Saves money on AI agent usage (input tokens) with the CI mode
• Define build, test, release, and operations workflows in a readable DSL.
• Replace ad hoc shell scripts or large Makefiles with named tasks.
• Add validation, defaults, and tool checks to task parameters and project workflows.
• Share automation in a form non-authors can still review.
• Keep AI guidance close to the automation with project skills.

Install

Use the install script:

curl -sSL https://raw.githubusercontent.com/phillarmonic/drun/master/install.sh | bash

Or install with Go:

go install github.com/phillarmonic/drun/v2/cmd/xdrun@latest

See the install guide for platform notes, pinned versions, and verification.

Quick Start

Create .drun/spec.drun:

version: 2.0

task "hello" means "Say hello":
  info "Hello from drun"

Then run it:

xdrun hello

You can also initialize a starter spec:

xdrun --init

Install AI guidance files for a repository that uses drun:

xdrun cmd:skill install drun-basics

See getting started for initialization options, templates, task parameters, dry runs, and shell autocomplete.

Editor Support

Using VS Code? Install the official extension with LSP support from the VS Code Marketplace.

Using Cursor, Antigravity, or another VS Code fork? Install the official extension from the Open VSX Registry.

Using a JetBrains IDE? Install the official plugin from the JetBrains Marketplace.

Highlights

• English-like task syntax.
• Context-aware shell completion for tasks and declared key=value parameter names.
• key=value task parameters with CLI flags kept separate.
• Built-in validation, defaults, and control flow.
• Dry-run support for inspecting execution.
• Task modes, including CI buffering and one-run overrides via --task-mode.
• Optional run ... attached mode for REPL-style commands that need stdin and a terminal.
• Reusable task files and examples for common workflows.
• Orchestration support for multi-service projects.

Learn More

• Getting started: installation, initialization, running tasks, and templates
• AI integration: install guidance files for AI agents
• Troubleshooting: common installation and usage problems
• Language reference: language specification
• Runtime and tool requirements: detection, execution, and errors
• Git policy hooks: branch and commit policy enforcement
• Examples: examples
• Orchestration: orchestration guide
• Stateless and partial names: stateless mode and partial names
• Developer documentation: developer guide
• Architecture: architecture