steps

steps

Pipelines where an agent is just another step.

steps runs Concourse-style YAML pipelines — get, task, put — from one Go binary, and adds agent: an LLM with tool calls, sub-agents, and MCP servers, sitting in the plan beside everything else. Every step is content-addressed and cached in SQLite, checked by assert:, and shown in a run transcript with what it cost.

Why

• An agent is a step. Same inputs:/outputs: as a task, same cache, same transcript. What it can touch is the tool grant: no edit_file means it reviews and cannot change code.
• A model proposes, a deterministic step disposes. verdicts: route the plan on the model's decision; assert: checks it wrote what it claimed; approval: parks the run for a person. An agent that reports success while writing nothing is caught by the pipeline, not by you.
• Every step is cached, replayable, priced. An unchanged commit re-runs nothing. steps plan says what would run before it costs anything. --replay --from re-runs one expensive step. The transcript shows spend against its ceiling.

Install

brew tap jtarchie/steps https://github.com/jtarchie/steps && brew install steps   # macOS
go install github.com/jtarchie/steps@latest                                       # any platform with Go 1.26+

Linux tarballs for each arch are on the releases page; the tap ships a cask, which Homebrew on Linux does not install.

Sixty seconds

Three files. Each is the previous one plus one idea, and each runs as written.

1 · A task.

# hello.yml
jobs:
- name: hello
  plan:
  - task: greet
    run: echo "hello from steps"

steps run hello.yml

2 · A resource. git is built in, so there is no resource_types: block to write.

# build.yml
resources:
- name: repo
  type: git
  source: { uri: https://github.com/jtarchie/steps.git, branch: main }

jobs:
- name: build
  plan:
  - get: repo
  - task: compile
    inputs: [repo]          # a step sees only the artifacts it declares
    run: cd repo && go build ./...

Run it twice. The second run fetches nothing and compiles nothing: the commit, the command and the declared inputs hash the same, so every step is replayed from cache.

3 · An agent, gated by things a model cannot talk its way past.

# review.yml
resources:
- name: repo
  type: git
  source: { uri: https://github.com/jtarchie/steps.git, branch: main }

agents:
- name: reviewer
  source: { model: openrouter/qwen/qwen3.7-flash, api_key_env: OPENROUTER_API_KEY }
  system: You review changes. Be terse.
  tools: [read_file, search_files, write_file]   # no edit_file: it reviews, it cannot change code

jobs:
- name: review
  plan:
  - get: repo
  - agent: reviewer
    inputs: [repo]
    outputs: [report]
    messages:
      - Read repo/ and write a one-paragraph risk summary to report/summary.md.
    verdicts:
      - approve: publish            # the decision picks the next step
      - reject: escalate
    assert:
      files: [report/summary.md]    # ...and it must have actually written it
  - task: escalate
    run: echo paging a human
  - task: publish
    inputs: [report]
    run: cat report/summary.md

OPENROUTER_API_KEY=... steps run review.yml

Swap the model for yours: any OpenAI-compatible endpoint, OpenRouter, a gateway (vercel/, requesty/, helicone/), a local server that needs no key (lmstudio/your-model), or a CLI you already have ("@claude/sonnet"). steps validate review.yml tells you before a run whether the key is set and the model resolves.

See it run

steps web is the daemon: it serves the browser UI, holds the pipelines you upload into it, polls every trigger: true resource, and runs what they enqueue.

steps web                                  # http://127.0.0.1:8088
steps pipeline set -c review.yml           # upload a pipeline into it

The run page is the transcript at the top of this file: every step in plan order, blocks folded under a rail, a cached step dimmed and labeled, an agent step expanded into its conversation with every tool call and result, and a spend panel that shows each step's cost against the ceiling it ran under. A run still in flight streams to the page as it happens. See docs/web.md.

Real pipelines

Every YAML example in docs/ is also a complete pipeline the test suite extracts and executes, so it runs as shown.

Commands

Exit codes: 0 success, 1 a step failed, 2 the pipeline could not be run (config or infrastructure), 130 interrupted.

Learn more

• docs/ — the reference, one page per feature. Start with resources, then control flow or agents.
• steps.schema.json — JSON Schema for the pipeline format. Put # yaml-language-server: $schema=./steps.schema.json on the first line of a pipeline for completion and inline errors in your editor.
• CLAUDE.md — architecture, build constraints, and contribution notes for anyone (human or agent) changing this codebase.

Build from source

go build -v     # Go 1.26+
task            # the whole validation sequence: fmt, lint, test (-race), build, vuln