Claude Code + OrchStep

You just spent twenty minutes in Claude Code seeding a staging environment: applied migrations, loaded fixtures, hit the health endpoint, confirmed a 200. It worked. The session scrolls off screen, and tomorrow you'll do it again from memory.

Claude Code is excellent at solving a task once. What it doesn't give you is the second run — the cheap, boring, identical replay. That's the gap OrchStep fills, and the two fit together in a way that's worth wiring up properly: capture what the agent did, then let the agent call it back when it needs it.

Step 1: capture the session

When the task is done, ask Claude Code to capture it:

/orchstep-capture seed-staging "apply migrations, load fixtures, smoke test"

The orchstep-capture skill reads the session history — the shell commands, the HTTP call, the git operations — and writes a clean workflow. It drops the noise (ls, cd, the failed first attempt at the fixtures path) and pulls the hardcoded values out into variables. What you get back isn't a transcript; it's a workflow:

name: seed-staging
# Captured from a Claude Code session, then cleaned: hardcoded values
# became vars, ls/cd/failed-retry noise was dropped.
defaults:
  service: orders
  target: staging
  migrations: "0042"

tasks:
  # `orchstep run seed`
  seed:
    steps:
      - name: migrate
        func: shell
        do: echo "applying migrations through {{ vars.migrations }} on {{ vars.target }}"
      - name: load-fixtures
        func: shell
        do: echo "loading fixtures for {{ vars.service }}"
        retry:
          max_attempts: 3
          interval: "1s"
      - name: smoke
        func: shell
        do: echo "GET /{{ vars.service }}/health -> 200"
        outputs:
          status: '{{ result.output | regexFind "[0-9]{3}" }}'
      - name: check
        func: assert
        args:
          condition: '{{ eq steps.smoke.status "200" }}'
          message: "staging smoke must return 200"

The flaky fixtures step came back with a retry. The smoke check became a real assert that fails loudly instead of a line you eyeball. And service, target, and migrations are variables, so the same workflow seeds orders today and billing tomorrow with --var service=billing.

Step 2: let Claude Code call it back

Now the workflow exists, you don't want to paste YAML into chat to run it. OrchStep ships an MCP server so the agent can call your workflows as tools. Point Claude Desktop at it:

{
  "mcpServers": {
    "orchstep": {
      "command": "orchstep",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/project"
    }
  }
}

Now the agent has structured tools: orchstep.list_tasks to see what's available, orchstep.lint to check a workflow before running it, and orchstep.run to execute a task and get structured JSON back — which step ran, what it output, whether it passed. The agent isn't parsing terminal scrollback; it's reading a result object.

A typical loop looks like this:

1. orchstep.list_tasks            -> sees "seed" is available
2. orchstep.lint                  -> confirms the workflow is valid
3. orchstep.run { task: "seed",
     vars: { service: "billing" },
     format: "json" }             -> runs it, reads the result
4. on failure, inspect the steps[] array and fix

The agent does the deciding; OrchStep does the doing — deterministically, the same way every time, whether a human or an agent pulls the trigger.

Why split it this way

The agent is the brain for the parts that need a brain. The workflow is the muscle memory for the parts that don't. You stop paying the agent to re-derive the same procedure, and you get a result you can diff, review, and trust.

Where to go next

• LLM Agent Integration — how agents author and run workflows
• MCP Server — the tools the agent calls
• Skills — the capture skill in detail
• Quick Start — your first workflow in two minutes

Just finished a multi-step task in Claude Code? /orchstep-capture it before the session scrolls away.