GitHub - shiehn/DeclarAgent: Declarative runbook executor for AI agents. Validate, dry-run, and safely run real CLI workflows.

Declarative runbook executor for AI agents. Validate, dry-run, and safely execute multi-step YAML workflows from any LLM tool-use loop.

Why DeclarAgent?

LLM agents are great at reasoning but dangerous when executing. DeclarAgent gives agents a structured, auditable, and safe way to run real workflows:

• YAML plans — human-readable, version-controllable runbooks
• Three step types — shell commands (run), built-in actions (action), and HTTP requests (http)
• Dry-run & explain — inspect exactly what will happen before it does
• Destructive-step gating — steps marked destructive: true require explicit --approve
• Structured JSON results — every run returns machine-readable output with typed errors
• Built-in actions — file I/O, JSON manipulation, and env access without shell gymnastics
• Template engine — reference outputs from prior steps with ${{steps.<id>.outputs.<key>}}
• MCP server — expose plans as directly callable tools over the Model Context Protocol
• Plan-as-tool — drop YAML files in a directory, each becomes an MCP tool automatically

Installation

Requires Go. This project is currently only tested on macOS.

go install github.com/shiehn/declaragent@latest

# Verify
declaragent --help

Platform note: Linux should work out of the box (the codebase uses sh -c with no OS-specific code). Windows requires WSL or a similar POSIX-compatible shell.

Quick Start

# Validate a plan
declaragent validate plan.yaml

# See what it would do
declaragent explain plan.yaml --input branch=main

# Dry-run (resolves templates, shows commands)
declaragent dry-run plan.yaml --input branch=main

# Execute for real
declaragent run plan.yaml --input branch=main

# Execute with destructive steps allowed
declaragent run plan.yaml --input branch=main --approve

# Start MCP server with a plans directory
declaragent mcp --plans ./plans

Plan Schema

Plans are YAML files with a simple structure. Each step does exactly one thing: run a shell command, call a built-in action, or send an HTTP request.

name: deploy-service
description: Build, test, and deploy the service
inputs:
  env:
    required: true
    description: Target environment
  tag:
    default: latest
steps:
  - id: test
    run: go test ./...
    outputs:
      result: stdout

  - id: build
    run: docker build -t myapp:${{inputs.tag}} .

  - id: check_health
    http:
      url: "https://${{inputs.env}}.example.com/health"
      method: GET
    outputs:
      status: stdout

  - id: deploy
    run: kubectl apply -f k8s/${{inputs.env}}.yaml
    destructive: true

Step Types

Each step must have exactly one of run, action, or http.

HTTP Step Fields

- id: call_api
  http:
    url: "https://api.example.com/data"    # required
    method: POST                            # default: GET
    headers:
      Authorization: "Bearer ${{inputs.token}}"
    body: '{"key": "value"}'               # template-resolved string
  outputs:
    response: stdout                        # response body

Key Fields

CLI Commands

All commands accept --json for machine-readable output and --input key=value for plan inputs.

Built-in Actions

Structured Results

Every execution returns a JSON result:

{
  "run_id": "a1b2c3",
  "success": true,
  "steps": [
    {"id": "test", "status": "success", "exit_code": 0, "duration": "1.2s"}
  ],
  "outputs": {"test.result": "ok"},
  "artifacts": [".declaragent/a1b2c3/test/stdout"],
  "errors": []
}

Errors are typed for agent decision-making:

MCP Integration

Run declaragent mcp to start a Model Context Protocol stdio server.

Plan-as-Tool

When you pass --plans <directory>, every YAML plan in that directory becomes a directly callable MCP tool:

declaragent mcp --plans ./plans

• Tool name = plan name
• Tool description = plan description
• Tool inputSchema = derived from plan inputs
• Calling the tool = executing the plan with the provided inputs

This means an LLM agent can discover and invoke your plans without knowing anything about DeclarAgent's internal plan format.

Integrations

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "declaragent": {
      "command": "/path/to/declaragent",
      "args": ["mcp", "--plans", "/path/to/your/plans"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "declaragent": {
      "command": "/path/to/declaragent",
      "args": ["mcp", "--plans", "/path/to/your/plans"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "declaragent": {
      "command": "/path/to/declaragent",
      "args": ["mcp", "--plans", "/path/to/your/plans"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "declaragent": {
      "command": "/path/to/declaragent",
      "args": ["mcp", "--plans", "/path/to/your/plans"]
    }
  }
}

GitHub Copilot (VS Code)

Add to .vscode/mcp.json in your project root. Note: Copilot uses "servers" instead of "mcpServers":

{
  "servers": {
    "declaragent": {
      "command": "/path/to/declaragent",
      "args": ["mcp", "--plans", "/path/to/your/plans"]
    }
  }
}

Amazon Q Developer

Add to ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "declaragent": {
      "command": "/path/to/declaragent",
      "args": ["mcp", "--plans", "/path/to/your/plans"]
    }
  }
}

ChatGPT

ChatGPT requires a remotely accessible SSE endpoint. See SSE Transport below, then add the public URL in ChatGPT's MCP settings.

SSE Transport

For remote hosting or HTTP-based clients (e.g., ChatGPT), start the MCP server with SSE transport:

declaragent mcp --transport sse --port 19100 --plans ./plans

The server will be available at http://localhost:19100/sse. Expose this URL publicly (e.g., via a reverse proxy or tunnel) for clients that require a remote endpoint.

Built-in MCP Tools

These meta-tools are always available regardless of --plans:

Claude Code Skills

As an alternative to MCP, you can generate a Claude Code Skill that teaches Claude Code how to use the DeclarAgent CLI directly. Skills are simpler and more token-efficient than MCP since they work through the CLI rather than a server.

# Generate a skill with a plan catalog
declaragent skill --plans ./plans

# Custom output directory and binary name
declaragent skill --plans ./plans --output .claude/skills/declaragent --binary declaragent

This creates .claude/skills/declaragent/SKILL.md containing CLI usage instructions and a catalog of your available plans. Claude Code automatically discovers skills in .claude/skills/, so once generated, any user (or agent) can invoke it via /declaragent.

Docs: 3 Example Plans You Can Copy and Run

Copy these into a plans/ directory and start the MCP server:

mkdir -p plans
# (paste each YAML below into the corresponding file)
declaragent mcp --plans ./plans

Or run any plan directly:

declaragent run plans/hello.yaml --input name=Alice

Plan 1: plans/hello.yaml — Simple Shell Command

The simplest possible plan. Runs echo and captures the output.

name: hello
description: Say hello to someone
inputs:
  name:
    description: Who to greet
    default: World
steps:
  - id: greet
    run: echo "Hello, ${{inputs.name}}!"
    outputs:
      message: stdout

Run it:

declaragent run plans/hello.yaml --input name=Alice

Result:

Plan "hello" completed successfully.
Run ID: <uuid>

With --json:

{
  "run_id": "...",
  "success": true,
  "steps": [{"id": "greet", "status": "success", "stdout_ref": "Hello, Alice!\n"}]
}

Plan 2: plans/ip_lookup.yaml — HTTP Request

Fetches your public IP address from a free API.

name: ip-lookup
description: Look up your public IP address
steps:
  - id: fetch_ip
    http:
      url: "https://httpbin.org/ip"
      method: GET
    outputs:
      response: stdout

Run it:

declaragent run plans/ip_lookup.yaml --json

Result:

{
  "success": true,
  "steps": [{
    "id": "fetch_ip",
    "status": "success",
    "stdout_ref": "{\"origin\": \"203.0.113.42\"}"
  }]
}

Plan 3: plans/build_and_notify.yaml — Multi-Step with Chaining

Runs a build, then POSTs the result to a webhook. Demonstrates step chaining — the HTTP step uses the shell step's output via ${{steps.build.outputs.result}}.

name: build-and-notify
description: Run a build command and POST the result to a webhook
inputs:
  webhook_url:
    required: true
    description: URL to POST the build result to
steps:
  - id: build
    run: echo "build-ok"
    outputs:
      result: stdout

  - id: notify
    http:
      url: "${{inputs.webhook_url}}"
      method: POST
      headers:
        Content-Type: application/json
      body: '{"event": "build_complete", "output": "${{steps.build.outputs.result}}"}'
    outputs:
      response: stdout

Run it:

declaragent run plans/build_and_notify.yaml \
  --input webhook_url=https://httpbin.org/post --json

This runs echo "build-ok", captures the output, then POSTs it to the webhook URL.

Testing

CI / Releases

All pushes to main and pull requests run tests automatically via GitHub Actions.

To create a new release, tag a commit and push the tag:

git tag v0.2.0
git push origin v0.2.0

This triggers the release workflow which:

1. Runs the full test suite
2. Builds binaries for macOS (arm64, amd64) and Linux (arm64, amd64)
3. Creates a GitHub Release with the binaries attached and auto-generated release notes

License

See LICENSE.