opcode

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.

# 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                                                |
| ---------------- | ------ | -------- | ----------------------------------------------