Capture an agent session, replay it for free

Your coding agent just did something genuinely useful. It provisioned a staging database, ran the migrations in the right order, seeded the fixtures, and verified the revision landed. It took twenty minutes of back-and-forth, a few wrong turns, and a non-trivial pile of tokens.

Now you need to do it again next week. So the agent reasons through the whole thing again, from scratch, at full price.

That is the waste OrchStep's capture skill removes. The reasoning is the expensive part, and you only have to pay for it once. Once the agent has solved the problem, the result is a fixed sequence of commands — a recipe. Capture compresses the solved session into a replayable orchstep.yml, and every replay after that runs the recipe directly, with no model in the loop.

What capture actually does

When you run /orchstep-capture at the end of a solved task, the skill reads back through the session and keeps only the real work:

• It identifies the goal, the key actions (shell commands, file edits, HTTP calls, git operations), and the verification steps.
• It throws away the noise — the ls, the cd, the failed retries, the dead ends the agent backed out of.
• It pulls hardcoded values up into vars placeholders so the workflow is reusable, not a one-shot transcript.
• It writes a workflow plus an environment template alongside it.

You get a clean artifact instead of a chat log. Here is the kind of thing a captured "provision staging" session collapses into:

name: provision-staging-db
defaults:
  target: staging
  version: "1.4.0"
tasks:
  provision:
    steps:
      - name: migrate
        func: shell
        do: echo "applying migrations for {{ vars.version }}"
        outputs:
          revision: '{{ result.output | regexFind "for (.+)" }}'
      - name: seed
        func: shell
        do: echo "seeding {{ vars.target }} at {{ steps.migrate.revision }}"
      - name: verify
        func: assert
        args:
          condition: '{{ ne steps.migrate.revision "" }}'
          message: "migration revision must be set"

The twenty-minute exploration became three steps you can read in ten seconds. The version is a variable, not a literal buried in a command. The verification the agent did by eye is now an assert that fails loudly if the revision is empty.

Replaying costs nothing

This is the part that changes the economics. To run it again:

orchstep run provision --var version=1.5.0 --var target=staging

No agent. No model call. No tokens. It is a binary executing a deterministic plan. The capture skill describes the output as a workflow you can "replay later with orchstep run or use as a regression test that other agents can re-run to verify the behavior still works." That second use is underrated: a captured workflow is a behavior contract. If the replay still passes next month, the thing the agent fixed is still fixed.

Smart capture vs. raw

Capture has two modes. The default is smart capture: it auto-deduplicates repeated work and classifies each action into the right OrchStep function (shell, http, git, and so on). If you want a faithful transcript instead — every step exactly as it happened, no cleanup — pass --raw. Use smart for something you will reuse, raw when you are debugging what the agent actually did.

Invocation is just:

/orchstep-capture provision-staging-db "provision and seed the staging database"

The name and description are optional; the skill will infer them from the session if you leave them off.

When this is worth it

Capture pays off when a task is repeatable and was expensive to figure out: deploys, data refreshes, environment setup, multi-step debugging fixes, infra changes. If the thing you did was a genuine one-off — a manual investigation you will never repeat — there is nothing to replay, so skip it. The value is in turning solved-once into runnable-forever.

Where to go next

• Capture skill — what the skill keeps, drops, and parameterizes
• LLM Agent Integration — how agents author and run workflows
• Variables & Outputs — the scoping model capture uses for its variable placeholders

Just watched your agent solve something the hard way? Run /orchstep-capture before the context scrolls away — the next run is free.