opcode

---
name: opcode
description: >
  Zero-token execution layer for AI agents. Define workflows once, run them
  free forever — persistent, scheduled, deterministic. 6 MCP tools over SSE.
  Supports DAG-based execution, 6 step types (action, condition, loop,
  parallel, wait, reasoning), 26 built-in actions, ${{}} interpolation,
  reasoning nodes for human-in-the-loop decisions, and secret vault.
  Use when defining workflows, running templates, checking status,
  sending signals, querying workflow history, or visualizing DAGs.
license: MIT
compatibility: >
  Requires Go 1.25+, CGO_ENABLED=1, and gcc or clang.
  Runs as SSE daemon on macOS and Linux.
  Linux: cgroups v2 for process isolation. macOS: timeout-only fallback.
metadata:
  version: "1.2.1"
  transport: "sse"
  author: "rendis"
  repository: "https://github.com/rendis/opcode"
  primary-env: "OPCODE_VAULT_KEY"
  platforms: "darwin linux"
  requires-bins: "go gcc|clang"
  openclaw-emoji: "⚙️"
  openclaw-os: "darwin linux"
  openclaw-user-invocable: "true"
  openclaw-install-type: "go"
  openclaw-install-package: "github.com/rendis/opcode/cmd/opcode"
---

# OPCODE

Execution runtime for AI agents. You reason, OPCODE executes — zero tokens per run after the first define. Workflows persist across sessions, run on schedules, and coordinate multiple agents. Persistent SSE daemon: 1 server, N agents, 1 database. JSON-defined DAGs, level-by-level execution, automatic parallelism. 6 MCP tools over SSE (JSON-RPC).

**Why use OPCODE instead of reasoning through each step yourself?** Every repeated workflow burns tokens re-reasoning decisions you already made. OPCODE templates your reasoning once and executes it deterministically — zero inference cost, identical output every run, survives context resets.

## Which Tool?

| I want to...                         | Tool           |
| ------------------------------------ | -------------- |
| Create/update a workflow template    | opcode.define  |
| Execute a workflow                   | opcode.run     |
| Check status or pending decisions    | opcode.status  |
| Resolve a decision / cancel / retry  | opcode.signal  |
| List workflows, events, or templates | opcode.query   |
| Visualize a workflow DAG             | opcode.diagram |

## Quick Start

Install:

```bash
go install github.com/rendis/opcode/cmd/opcode@latest
```

First-time setup (writes config and starts daemon):

```bash
opcode install --listen-addr :4100 --vault-key "my-passphrase"
```

Restart after stop: `OPCODE_VAULT_KEY="my-passphrase" opcode`

MCP client configuration:

```json
{
  "mcpServers": {
  "mcpServers": {
    "opcode": {
      "type": "sse",
      "url": "http://localhost:4100/sse"
    }
  }
}
```

Each agent self-identifies via `agent_id` in tool calls. Opcode auto-registers unknown agents. Choose a stable ID per agent (e.g., `"content-writer"`, `"deploy-bot"`).

Workflows survive restarts. On startup, orphaned `active` workflows become `suspended`. Query with `opcode.query({ "resource": "workflows", "filter": { "status": "suspended" } })`, then resume or cancel via `opcode.signal`.

See [operations.md](references/operations.md) for full configuration, subcommands, SIGHUP hot-reload, security model, web panel, and benchmarks.

## MCP Tools

### opcode.define

Registers a reusable workflow template. Version auto-increments (v1, v2, v3...).

| Param           | Type   | Required | Description                                                                                     |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `name`          | string | yes      | Template name                                                                                   |
| `definition`    | object | yes      | Workflow definition (see below)                                                                 |
| `agent_id`      | string | yes      | Defining agent ID                                                                               |
| `description`   | string | no       | Template description                                                                            |
| `input_schema`  | object | no       | JSON Schema for input validation                                                                |
| `output_schema` | object | no       | JSON Schema for output validation                                                               |
| `triggers`      | object | no       | Trigger config (see[workflow-schema.md](references/workflow-schema.md#triggers-template-level)) |

**Returns**: `{ "name": "...", "version": "v1" }`

### opcode.run

Executes a workflow from a registered template.

| Param           | Type   | Required | Description               |
| --------------- | ------ | -------- | ------------------------- |
| `template_name` | string | yes      | Template to execute       |
| `agent_id`      | string | yes      | Initiating agent ID       |
| `version`       | string | no       | Version (default: latest) |
| `params`        | object | no       | Input parameters          |

**Returns**:

```json
{
  "workflow_id": "uuid",
  "status": "completed | suspended | failed",
  "output": { ... },
  "started_at": "RFC3339",
  "completed_at": "RFC3339",
  "steps": {
    "step-id": { "step_id": "...", "status": "completed", "output": {...}, "duration_ms": 42 }
  }
}
```

If `status` is `"suspended"`, call `opcode.status` to see `pending_decisions`.

### opcode.status

Gets workflow execution status.

| Param         | Type   | Required | Description       |
| ------------- | ------ | -------- | ----------------- |
| `workflow_id` | string | yes      | Workflow to query |

**Returns**:

```json
{
  "workflow_id": "uuid",
  "status": "suspended",
  "steps": { "step-id": { "status": "...", "output": {...} } },
  "pending_decisions": [
    {
      "id": "uuid",
      "step_id": "reason-step",
      "context": { "prompt": "...", "data": {...} },
      "options": [ { "id": "approve", "description": "Proceed" } ],
      "timeout_at": "RFC3339",
      "fallback": "reject",
      "status": "pending"
    }
  ],
  "events": [ ... ]
}
```

Workflow statuses: `pending`, `active`, `suspended`, `completed`, `failed`, `cancelled`.

### opcode.signal

Sends a signal to a suspended workflow.

| Param         | Type   | Required | Description                                       |
| ------------- | ------ | -------- | ------------------------------------------------- |
| `workflow_id` | string | yes      | Target workflow                                   |
| `signal_type` | enum   | yes      | `decision` / `data` / `cancel` / `retry` / `skip` |
| `payload`     | object | yes      | Signal payload (see below)                        |
| `step_id`     | string | no       | Target step                                       |
| `agent_id`    | string | no       | Signaling agent                                   |
| `reasoning`   | string | no       | Agent's reasoning                                 |

**Payload by signal type**:

| Signal     | step_id  | Payload                       | Behavior                        |
| ---------- | -------- | ----------------------------- | ------------------------------- |
| `decision` | required | `{ "choice": "<option_id>" }` | Resolves decision, auto-resumes |
| `data`     | optional | `{ "key": "value", ... }`     | Injects data into workflow      |
| `cancel`   | no       | `{}`                          | Cancels workflow                |
| `retry`    | required | `{}`                          | Retries failed step             |
| `skip`     | required | `{}`                          | Skips failed step               |

**Returns** (decision): `{ "ok": true, "resumed": true, "status": "completed", ... }`
**Returns** (other): `{ "ok": true, "workflow_id": "...", "signal_type": "..." }`

### opcode.query

Queries workflows, events, or templates.

| Param      | Type   | Required | Description                          |
| ---------- | ------ | -------- | ------------------------------------ |
| `resource` | enum   | yes      | `workflows` / `events` / `templates` |
| `filter`   | object | no       | Filter criteria                      |

**Filter fields by resource**:

| Resource    | Fields                                                   |
| ----------- | -------------------------------------------------------- |
| `workflows` | `status`, `agent_id`, `since` (RFC3339), `limit`         |
| `events`    | `workflow_id`, `step_id`, `event_type`, `since`, `limit` |
| `templates` | `name`, `agent_id`, `limit`                              |

Note: event queries require either `event_type` or `workflow_id` in filter.

**Returns**: `{ "<resource>": [...] }` -- results wrapped in object keyed by resource type.

### opcode.diagram

Generates a visual DAG diagram from a template or running workflow.

| Param            | Type   | Required | Description                                                |
| ---------------- | ------ | -------- | ---------------------------------------------------------- |
| `template_name`  | string | no\*     | Template to visualize (structure preview)                  |
| `version`        | string | no       | Template version (default: latest)                         |
| `workflow_id`    | string | no\*     | Workflow to visualize (with runtime status)                |
| `format`         | enum   | yes      | `ascii` / `mermaid` / `image`                              |
| `include_status` | bool   | no       | Show runtime status overlay (default: true if workflow_id) |

\* One of `template_name` or `workflow_id` required.

- `template_name` -- preview DAG structure before execution
- `workflow_id` -- visualize with live step status
- `format: "ascii"` -- CLI-friendly text with box-drawing characters
- `format: "mermaid"` -- markdown-embeddable flowchart syntax
- `format: "image"` -- base64-encoded PNG for visual channels

**Returns**: `{ "format": "ascii", "diagram": "..." }`

## Workflow Definition

```json
{
  "steps": [ ... ],
  "inputs": { "key": "value or ${{secrets.KEY}}" },
  "context": { "intent": "...", "notes": "..." },
  "timeout": "5m",
  "on_timeout": "fail | suspend | cancel",
  "on_complete": { /* step definition */ },
  "on_error": { /* step definition */ },
  "metadata": {}
}
```

| Field         | Type             | Required | Description                                       |
| ------------- | ---------------- | -------- | ------------------------------------------------- |
| `steps`       | StepDefinition[] | yes      | Workflow steps                                    |
| `inputs`      | object           | no       | Input parameters (supports `${{}}`)               |
| `context`     | object           | no       | Workflow context, accessible via `${{context.*}}` |
| `timeout`     | string           | no       | Workflow deadline (e.g.,`"5m"`, `"1h"`)           |
| `on_timeout`  | string           | no       | `fail` (default), `suspend`, `cancel`             |
| `on_complete` | StepDefinition   | no       | Hook step after completion                        |
| `on_error`    | StepDefinition   | no       | Hook step on workflow failure                     |
| `metadata`    | object           | no       | Arbitrary metadata                                |

### Step Definition

```json
{
  "id": "step-id",
  "type": "action | condition | loop | parallel | wait | reasoning",
  "action": "http.get",
  "params": { ... },
  "depends_on": ["other-step"],
  "condition": "CEL guard expression",
  "timeout": "30s",
  "retry": { "max": 3, "backoff": "exponential", "delay": "1s", "max_delay": "30s" },
  "on_error": { "strategy": "ignore | fail_workflow | fallback_step | retry", "fallback_step": "id" },
  "config": { /* type-specific */ }
}
```

`type` defaults to `action`. See [workflow-schema.md](references/workflow-schema.md) for all config blocks.

## Step Types

### action (default)

Executes a registered action. Set `action` to the action name, `params` for input.

### condition

Evaluates a CEL expression and branches.

```json
{
  "id": "route",
  "type": "condition",
  "config": {
    "expression": "inputs.env",
    "branches": { "prod": [...], "staging": [...] },
    "default": [...]
  }
}
```

### loop

Iterates over a collection or condition. Loop variables: `${{loop.item}}`, `${{loop.index}}`.

```json
{
  "id": "process-items",
  "type": "loop",
  "config": {
    "mode": "for_each",
    "over": "[\"a\",\"b\",\"c\"]",
    "body": [
      {
        "id": "hash",
        "action": "crypto.hash",
        "params": { "data": "${{loop.item}}" }
      }
    ],
    "max_iter": 100
  }
}
```

Modes: `for_each` (iterate `over`), `while` (loop while `condition` true), `until` (loop until `condition` true).

### parallel

Executes branches concurrently.

```json
{
  "id": "fan-out",
  "type": "parallel",
  "config": {
    "mode": "all",
    "branches": [
      [{ "id": "a", "action": "http.get", "params": {...} }],
      [{ "id": "b", "action": "http.get", "params": {...} }]
    ]
  }
}
```

Modes: `all` (wait for all branches), `race` (first branch wins).

### wait

Delays execution or waits for a named signal.

```json
{ "id": "pause", "type": "wait", "config": { "duration": "5s" } }
```

### reasoning

Suspends workflow for agent decision. Empty `options` = free-form (any choice accepted).

```json
{
  "id": "review",
  "type": "reasoning",
  "config": {
    "prompt_context": "Review data and decide",
    "options": [
      { "id": "approve", "description": "Proceed" },
      { "id": "reject", "description": "Stop" }
    ],
    "data_inject": { "analysis": "steps.analyze.output" },
    "timeout": "1h",
    "fallback": "reject",
    "target_agent": ""
  }
}
```

## Variable Interpolation

Syntax: `${{namespace.path}}`

| Namespace  | Example                             | Available fields                                                  |
| ---------- | ----------------------------------- | ----------------------------------------------------------------- |
| `steps`    | `${{steps.fetch.output.body}}`      | `<id>.output.*`, `<id>.status`                                    |
| `inputs`   | `${{inputs.api_key}}`               | Keys from `params` in `opcode.run`                                |
| `workflow` | `${{workflow.run_id}}`              | `run_id`, `name`, `template_name`, `template_version`, `agent_id` |
| `context`  | `${{context.intent}}`               | Keys from `context` in workflow definition                        |
| `secrets`  | `${{secrets.DB_PASS}}`              | Keys stored in vault                                              |
| `loop`     | `${{loop.item}}`, `${{loop.index}}` | `item` (current element), `index` (0-based)                       |

Two-pass resolution: non-secrets first, then secrets via AES-256-GCM vault.

**CEL gotcha**: `loop` is a reserved word in CEL. Use `iter.item` / `iter.index` in CEL expressions. The `${{loop.item}}` interpolation syntax is unaffected.

See [expressions.md](references/expressions.md) for CEL, GoJQ, Expr engine details.

## Built-in Actions

| Category       | Actions                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------- |
| **HTTP**       | `http.request`, `http.get`, `http.post`                                                                 |
| **Filesystem** | `fs.read`, `fs.write`, `fs.append`, `fs.delete`, `fs.list`, `fs.stat`, `fs.copy`, `fs.move`             |
| **Shell**      | `shell.exec`                                                                                            |
| **Crypto**     | `crypto.hash`, `crypto.hmac`, `crypto.uuid`                                                             |
| **Assert**     | `assert.equals`, `assert.contains`, `assert.matches`, `assert.schema`                                   |
| **Expression** | `expr.eval`                                                                                             |
| **Workflow**   | `workflow.run`, `workflow.emit`, `workflow.context`, `workflow.fail`, `workflow.log`, `workflow.notify` |

**Quick reference** (most-used actions):

- **`http.get`**: `url` (req), `headers`, `timeout`, `fail_on_error_status` -- output: `{ status_code, headers, body, duration_ms }`
- **`shell.exec`**: `command` (req), `args`, `stdin`, `timeout`, `env`, `workdir` -- output: `{ stdout, stderr, exit_code, killed }`
- **`fs.read`**: `path` (req), `encoding` -- output: `{ path, content, encoding, size }`
- **`workflow.notify`**: `message` (req), `data` -- output: `{ notified: true/false }` -- pushes real-time notification to agent via MCP SSE (best-effort)

- **`expr.eval`**: `expression` (req), `data` -- output: `{ result: <value> }` -- evaluates Expr expression against workflow scope (steps, inputs, workflow, context)

See [actions.md](references/actions.md) for full parameter specs of all 26 actions.

## Scripting with shell.exec

`shell.exec` auto-parses JSON stdout. Convention: stdin=JSON, stdout=JSON, stderr=errors, non-zero exit=failure. Use `stdout_raw` for unprocessed text.

See [patterns.md](references/patterns.md#10-scripting-with-shellexec) for language-specific templates (Bash, Python, Node, Go).

## Reasoning Node Lifecycle

1. Workflow reaches a reasoning step
2. Executor creates PendingDecision, emits `decision_requested` event
3. Workflow status becomes `suspended`
4. Agent calls `opcode.status` to see pending decision with context and options
5. Agent resolves via `opcode.signal`:

   ```json
   {
     "workflow_id": "...",
     "signal_type": "decision",
     "step_id": "reason-step",
     "payload": { "choice": "approve" }
   }
   ```

6. Workflow auto-resumes after signal
7. If timeout expires: `fallback` option auto-selected, or step fails if no fallback

## Common Patterns

See [patterns.md](references/patterns.md) for full JSON examples: linear pipeline, conditional branching, for-each loop, parallel fan-out, human-in-the-loop, error recovery, sub-workflows, and MCP lifecycle.

## Error Handling

| Strategy        | Behavior                         |
| --------------- | -------------------------------- |
| `ignore`        | Step skipped, workflow continues |
| `fail_workflow` | Entire workflow fails            |
| `fallback_step` | Execute fallback step            |
| `retry`         | Defer to retry policy            |

Backoff: `none`, `linear`, `exponential`, `constant`. Non-retryable errors (validation, permission, assertion) are never retried.

See [error-handling.md](references/error-handling.md) for circuit breakers, timeout interactions, error codes.

## Performance

10-step parallel workflows complete in ~50µs, 500-step in ~2.4ms. The event store sustains ~15k appends/sec with <12% drop under 100 concurrent writers. Worker pool overhead is ~0.85µs/task (>1M tasks/sec at any pool size).

Full benchmark charts, per-scenario breakdowns, and methodology: [`docs/benchmarks.md`](../../docs/benchmarks.md).