Documentation/

Workflows

You explain things to your AI agent the same way every time. "Review this PR — check the diff, run lint, document any issues." You type it out, the agent does it, you move on. Next week, you type it again.

A workflow captures that. You write the instructions once in YAML, and run it whenever you need it. The AI follows your instructions, uses only the tools you allow, and produces consistent results every time.

Create a Workflow

8v workflow create review-pr

This creates .8v/workflows/review-pr.yaml. Open it and write your instructions:

name: review-pr
description: Review code changes and report issues

run_with:
  model: claude-sonnet-4-6

instructions: |
  Review the recent changes:
  1. Read the diff
  2. Run lint to check for issues
  3. Verify the approach makes sense
  4. If issues found, document them

allowed_actions:
  - project.search
  - project.lint
  - fs.read
  - git.diff
  - git.log

blocked_actions:
  - fs.write
  - fs.edit
  - git.push

Run It

8v workflow run review-pr

The daemon creates a chat session, sends your instructions to the model, and streams the response. You see the AI's output in real time — text chunks as it thinks, tool calls as it works.

Workflow 'review-pr' — model: claude-sonnet-4-6

The recent changes refactor the auth middleware...
  [project.lint] done (340ms)
No lint issues found. The approach looks clean...

Workflow 'review-pr' complete.
(12.3s)

What Each Field Does

instructions — what the AI should do. Write it like you'd explain the task to a colleague. Be specific.

allowed_actions — what tools the AI can use. If set, the AI is told it may only use these. Wildcards work: project.* allows all project tools.

blocked_actions — what tools the AI must not use. Use this to prevent writes, pushes, or destructive operations.

run_with — how the workflow runs. Two modes:

  • Provider + model (direct API) — the daemon calls the model's API directly. You store your API key with 8v credentials set anthropic or 8v credentials set openai, and the workflow uses it. No agent needed.
  • Agent — the daemon uses an installed agent CLI (Claude Code, Codex, Aider). The agent gets your project tools and follows the instructions.
# Direct API — daemon calls the model
run_with:
  model: claude-sonnet-4-6

# Or specify the provider explicitly
run_with:
  provider: anthropic
  model: claude-sonnet-4-6

# Agent — uses an installed CLI
run_with:
  agent: claude

If you only set model, the daemon resolves the provider from the model name. If you set agent, it launches that agent with your project tools connected.

inputs — parameters that get injected into the instructions. See below.

Parameters

Workflows accept parameters via --set:

name: investigate
description: Investigate a specific issue

inputs:
  issue_id:
    type: string
    required: true
  scope:
    type: string
    default: src/

instructions: |
  Investigate issue {{ issue_id }}.
  Focus on files in {{ scope }}.
  Search the codebase, read related code, document findings.

8v workflow run investigate --set issue_id=AUTH-142
8v workflow run investigate --set issue_id=AUTH-142 --set scope=crates/auth/

Missing a required input gives a clear error:

Error: Missing required input: issue_id
  Usage: 8v workflow run investigate --set issue_id=<value>

Override the Model

The YAML sets the default model. Override it from the CLI:

8v workflow run review-pr --model claude-opus-4-6

Preview Without Running

See the rendered prompt without sending it to the model:

8v workflow run review-pr --dry-run

Chains

A chain runs workflows in sequence. Each step completes before the next begins.

8v chain create release

Edit .8v/chains/release.yaml:

name: release
description: Investigate, fix, then review

steps:
  - workflow: investigate
  - workflow: fix
  - workflow: review

8v chain run release --set issue_id=AUTH-142

Parameters and model overrides pass through to every workflow in the chain:

8v chain run release --set issue_id=AUTH-142 --model claude-opus-4-6 --dry-run

List and Inspect

8v workflow list                    # Show all workflows
8v workflow show review-pr          # Show details, inputs, constraints

8v chain list                       # Show all chains
8v chain show release               # Show steps

Where They Live

Workflows live in .8v/workflows/ and chains in .8v/chains/. Plain YAML files — commit them to git. Your whole team runs the same workflows with the same constraints.

This Is Not CI/CD

Workflows don't run shell scripts. They give instructions to an AI model. The model reads code, calls tools, and produces output. Think of it as a repeatable prompt with guardrails — not a pipeline with steps.

The constraints (allowed_actions, blocked_actions) are instructions to the model, not hard enforcement. They tell the AI what it should and shouldn't do. The model respects these boundaries the same way it respects any system prompt instruction.

Next

Referenced by