runweave

Session orchestrator for Claude Code and Codex — run AI agent workflows from YAML definitions.

Features

• Declare workflows in YAML: prompt, trigger, agent backend, workspace hooks
• Two trigger types: cron schedule and manual (runweave run)
• Two agent backends: Claude Code (@anthropic-ai/claude-agent-sdk) and Codex (@openai/codex-sdk)
• Four permission modes: autonomous, full-auto, supervised, readonly
• Workspace isolation per session with lifecycle hooks
• Session state persistence (flat files, no database)
• Hot reload — YAML changes are picked up without restarting the daemon
• Desktop and webhook notifications

Prerequisites

• Node.js 20+
• pnpm
• Claude Code CLI — required when using the claude-code backend
• Codex CLI — required when using the codex backend

Installation

npm install -g runweave

Quick Start

# 1. Initialize a project
runweave init

# 2. Edit the generated workflow
#    workflows/example.yaml is created automatically

# 3. Run it immediately
runweave run workflows/example.yaml

runweave init creates workflows/example.yaml and a .gitignore that excludes workspace directories.

Workflow YAML Reference

Minimal configuration

name: fix-issues
prompt: |
  Fix the assigned GitHub issues.

trigger defaults to manual, agent.backend to claude-code, agent.mode to autonomous.

Full configuration

name: fix-assigned-issues
description: "Auto-fix assigned GitHub issues every morning"

trigger:
  cron: "0 9 * * *"

agent:
  backend: claude-code
  mode: autonomous
  model: opus
  provider_options:
    setting_sources:
      - project
      - local

context:
  github_token: $GITHUB_TOKEN
  assignee: winor30
  repo: winor30/runweave

workspace:
  root: .runweave-workspaces
  hooks:
    after_create: "git clone https://github.com/{{ repo }}.git ."
    before_run: "git fetch origin && git checkout main"

concurrency:
  max: 1
  on_conflict: skip

notify:
  channels:
    - type: webhook
      url: $SLACK_WEBHOOK_URL
  on:
    completed: true
    failed: true

prompt: |
  Check open issues assigned to {{ assignee }} in {{ repo }}.
  Fix the highest-priority ones and open a PR for each fix.

notify is reserved for notification configuration. The notifier implementations exist in the codebase, but daemon wiring is still being finalized in the current release.

Default values

| Field | Default | Notes | | ------------------------- | ---------------------- | ------------------------------------------------------ | | trigger | { type: manual } | Omit to run only via runweave run | | agent.backend | claude-code | claude-code or codex | | agent.mode | autonomous | See Agent Modes below | | agent.model | SDK default | | | agent.provider_options | {} | Passed through to the SDK | | context | {} | Template variables for {{ var }} | | workspace.root | .runweave-workspaces | | | workspace.hooks | {} | after_create, before_run | | concurrency.max | 1 | Max concurrent runs of this workflow | | concurrency.on_conflict | skip | skip today; queue is reserved for a future release |

Trigger syntax

# Shorthand cron
trigger:
  cron: "0 9 * * *"

# Explicit cron
trigger:
  type: cron
  schedule: "0 9 * * *"

# Manual (default when trigger is omitted)
trigger:
  type: manual

Polling patterns are expressed as cron + prompt:

name: watch-project-board
trigger:
  cron: "*/30 * * * *"
prompt: |
  Check the GitHub Projects board for Ready issues and start working on them.

Template variables

Prompts and hook commands support Liquid templates ({{ var }}). Keys in context become template variables. Environment variables are referenced with $VAR_NAME and expanded at load time.

CLI Commands

runweave start [--workflows <dir>] [--no-watch]

Start the daemon. Registers all cron-triggered workflows in <dir> (default: workflows/). Watches the directory for YAML changes and hot-reloads them. Press Ctrl-C to stop.

runweave run <workflow.yaml> [--context key=value ...]

Execute a single workflow immediately without starting the daemon. Multiple --context flags are merged on top of the workflow's declared context.

runweave run workflows/fix-issues.yaml --context assignee=octocat

runweave status [--workflow <name>]

List all sessions and their current status. Filter by workflow name with --workflow.

SESSION   WORKFLOW     STATUS     BACKEND      STARTED
a1b2c3d4  fix-issues   running    claude-code  2026-03-24 09:00:00
e5f6a7b8  watch-board  completed  codex        2026-03-24 08:30:00

runweave logs <session-id> [--follow]

Print events for a session. --follow (-f) streams new events as they are appended.

runweave attach <session-id> [--message <text>]

Attach to a session and send messages. Without --message, enters interactive stdin mode — each line is sent as a separate prompt. Press Ctrl-D to detach (the session continues).

# One-shot message
runweave attach a1b2c3d4 --message "yes, proceed with the test command"

# Interactive
runweave attach a1b2c3d4

runweave stop <session-id>

Stop a running session.

runweave validate [path]

Validate a single workflow file or all .yaml/.yml files in a directory (default: workflows/). Exits non-zero if any file fails.

runweave validate workflows/fix-issues.yaml
runweave validate workflows/

runweave init [dir]

Initialize a runweave project. Creates workflows/example.yaml and .gitignore in dir (default: current directory). The generated .gitignore excludes runweave workspace and session directories. Existing files are not overwritten.

Agent Modes

| Mode | Description | Use case | | ------------ | -------------------------------------------------------------------- | ----------------------------------- | | autonomous | Agent runs without approval prompts (default) | Daemon / cron jobs | | full-auto | Same as autonomous but with unrestricted network/filesystem access | Tasks requiring full system access | | supervised | Pauses on tool calls outside the allowlist; resume with attach | Tasks where human oversight matters | | readonly | Restricted to read-only tools | Audits, reports, investigations |

When a supervised session is waiting for input, runweave status shows needs_input. Use runweave attach to review and respond.

License

MIT