Opcode

LLM agents burn tokens on repetitive tasks. Every API chain, every data pipeline, every approval flow — re-reasoned from scratch, every time.

OPCODE is the execution layer agents are missing. Define a workflow once, execute it forever — zero tokens, zero re-reasoning, deterministic every run. Persistent across sessions, schedulable without invocation, coordinating N agents through 6 MCP tools over SSE. Workflows are expressed as directed acyclic graphs (DAGs) with built-in support for reasoning nodes, flow control, event sourcing, process isolation, and secret management.

Why OPCODE?

| Without OPCODE | With OPCODE | | ------------------------------------- | ----------------------------------- | | Agent re-reasons every repeated flow | Reason once, template, execute free | | Workflows die with the context window | Persist across sessions and crashes | | Can't self-trigger at scheduled times | Cron scheduler runs autonomously | | Each run costs inference tokens | Each run costs zero tokens | | Output varies between identical runs | Deterministic, identical every time | | One agent, one thread | N agents on shared workflows |

Key Features

• MCP-native interface -- 6 tools (opcode.run, opcode.status, opcode.signal, opcode.define, opcode.query, opcode.diagram) over SSE — agents call one tool and the workflow executes without further inference
• DAG-based execution -- Automatic parallelism, level-by-level dispatch; a 10-step workflow completes in ~50µs with zero tokens spent
• Reasoning nodes -- Human-in-the-loop / agent-in-the-loop decision points that suspend workflows and resume on signal; decisions are stored once and never re-reasoned
• Event sourcing -- Append-only event log with materialized step states; workflows survive crashes and resume exactly where they left off
• Flow control & expressions -- Conditions (CEL), loops, parallel branches, wait steps, GoJQ transforms, Expr logic, ${{...}} interpolation — complex logic without inference cost
• Workflow diagrams -- Visual DAG in ASCII (CLI), Mermaid (markdown), or PNG (graphviz) with runtime status overlay
• Web management panel -- Built-in dashboard for multi-agent monitoring, decision resolution, and workflow management
• Process isolation -- Linux cgroups v2 (memory, CPU, PID namespace) with macOS fallback — safe execution of shell commands with resource limits
• Secret vault -- AES-256-GCM encrypted secrets with PBKDF2 key derivation; resolved at runtime via ${{secrets.KEY}} without exposing secrets in workflow definitions
• Plugins, scheduling & resilience -- Cron scheduler runs workflows autonomously (no agent invocation needed), MCP subprocess plugins with auto-restart, per-action circuit breakers

Table of Contents

• [Why OPCODE?](#why-opcode)
• [Performance](#performance)
• [Quick Start](#quick-start)
• [Agent Skill](#agent-skill)
• [Tech Stack](#tech-stack)
• [Examples](#examples)
• [Architecture](#architecture)
• [MCP Tools](#mcp-tools)
• [Workflow Diagrams](#workflow-diagrams)
• [Web Panel](#web-panel)
• [Workflow Basics](#workflow-basics)
• [Environment Variables](#environment-variables)
• [Testing](#testing)
• [Deployment](#deployment)
• [Troubleshooting](#troubleshooting)

Performance

Auto-generated by make benchmarks (go run ./cmd/gen-benchmarks). See [docs/benchmarks.md](docs/benchmarks.md) for full results, methodology, and per-scenario breakdowns.

> ↓ = lower is better · ↑ = higher is better

DAG Execution

Full workflow execution: DAG parse, level walk, WorkerPool dispatch, FSM transitions, event emission.

| Scenario | Latency ↓ | Throughput ↑ | | ------------------- | --------: | -----------: | | 10 parallel steps | ~47µs | ~21k wf/sec | | 100 parallel steps | ~449µs | ~2.2k wf/sec | | 500 parallel steps | ~2.4ms | ~422 wf/sec | | 5 sequential steps | ~24µs | ~42k wf/sec | | 50 sequential steps | ~200µs | ~5k wf/sec |

> A 10-step workflow completes in ~50µs. Even 500 parallel steps finish in ~2.4ms. Latency scales linearly — the engine adds ~4µs overhead per step regardless of execution mode.

Event Store (libSQL)

| Operation | Latency ↓ | Throughput ↑ | | -------------------- | --------: | ----------------: | | Append (sequential) | ~64µs | ~15.6k events/sec | | Append (100 writers) | ~73µs | ~13.7k events/sec | | Replay 1,000 events | ~6.4ms | — |

> ~15k event appends/sec with

All pool sizes (10-1000 workers) exceed 1M tasks/sec. Pool overhead is ~0.85µs per task — size barely affects CPU-bound throughput.

Quick Start

> Prerequisites: Go 1.25+, CGO enabled, GCC / C compiler (Xcode CLI Tools on macOS, gcc libc6-dev on Linux).

1. Clone & Build

git clone https://github.com/rendis/opcode.git
go build -C /path/to/opcode -o opcode ./cmd/opcode/

2. Run the Server

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

This writes ~/.opcode/settings.json, downloads mermaid-ascii for enhanced ASCII diagrams, and starts the daemon. The web panel is available at http://localhost:4100.

If the process stops, restart with:

OPCODE_VAULT_KEY="my-secret-passphrase" opcode

> For production, set OPCODE_VAULT_KEY as an env var in your process manager (systemd, launchd). The install step is only needed once.

3. Configure as an MCP Server

Add opcode to your MCP client configuration (.mcp.json):

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

4. Verify (optional)

go test -C /path/to/opcode ./... -count=1 -timeout 60s

All 981 tests should pass. For CLI-based tool testing, see [Connecting via mcporter](docs/mcp-tools.md#connecting-via-mcporter).

Agent Skill

OPCODE includes an agent skill that teaches AI coding agents (Claude Code, Cursor, etc.) how to define, execute, and manage workflows using the MCP tools. The skill provides reference documentation for workflow schemas, actions, expressions, error handling, and common patterns.

Install via skills.sh

npx skills add https://github.com/rendis/opcode --skill opcode

Install via ClawHub

npx clawhub@latest install opcode
# or
pnpm dlx clawhub@latest install opcode
# or
bunx clawhub@latest install opcode

Tech Stack

| Component | Technology | | ---------------------- | ------------------------------------------------------------------------------------ | | Language | Go 1.25+ | | Database | Embedded libSQL (via go-libsql, CGO required) | | MCP Server | mcp-go (SSE transport) | | Expression Engines | CEL (cel-go), GoJQ (gojq), Expr (expr-lang/expr) | | Validation | JSON Schema Draft 2020-12 (santhosh-tekuri/jsonschema/v6) | | Diagrams | goccy/go-graphviz (WASM-based, no CGO), ASCII box-drawing, Mermaid syntax | | Web Panel | Go html/template, htmx, Pico CSS, mermaid.js, SSE live updates | | Scheduling | robfig/cron/v3 | | IDs | UUIDs (google/uuid) | | Testing | testify, embedded libSQL for integration tests | | Isolation | Linux cgroups v2 + namespaces; macOS fallback (os/exec + timeout) | | Cryptography | AES-256-GCM (stdlib crypto/aes + crypto/cipher), PBKDF2 (stdlib crypto/pbkdf2) |

Examples

44 ready-to-use workflow definitions in [examples/](examples/):

| Category | Highlights | | --------------------- | --------------------------------------------------------------- | | Agent Ops | content-summarizer, multi-source-research, iterative-refinement | | DevOps / CI-CD | deploy-gate, log-anomaly-triage, health-check-sweep | | Data Pipelines | etl-with-validation, batch-file-processor, sync-drift-detection | | Human-in-the-Loop | approval-chain, free-form-decision, escalation-ladder | | Integrations | webhook-handler, lead-enrichment, two-way-sync | | Monitoring | error-aggregator, uptime-monitor, backup-verification | | Security | secret-rotation, dependency-audit | | E-Commerce | order-processing, invoice-generator, price-monitor |

Each example includes a workflow.json and a README.md with step-by-step explanation. See the full [examples catalog](examples/README.md) for feature index and script conventions.

Architecture

graph TB
    Agent["MCP Client (Agent)Claude, AI framework, etc."]
    Browser["Web Browser"]
    MCP["MCP Server (pkg/mcp)opcode.run / .status / .signalopcode.define / .query / .diagram"]
    Panel["Web Panel (internal/panel)Dashboard, Workflows, Decisions,Templates, Scheduler, Events"]
    Diagram["Diagram EngineASCII / Mermaid / PNG"]
    Exec["Executor (engine)DAG parse → level walk → WorkerPool"]
    Actions["Actions Registrybuilt-in + plugins"]
    FSMs["FSMsWorkflow + Step"]
    Retry["Retry /Circuit Breaker"]
    Reasoning["Reasoning Nodessuspend → signal → resume"]
    Isolation["Isolationcgroups v2 / fallback"]
    Expressions["ExpressionsCEL, GoJQ, Expr, ${{}}"]
    Store["Store (libSQL)workflows, events, step_state,decisions, templates, secrets"]
    Hub["EventHubSSE live updates"]

    Agent -->|"JSON-RPC over SSE"| MCP
    Browser -->|"HTTP + SSE"| Panel
    MCP --> Exec
    MCP --> Diagram
    Panel --> Store
    Panel --> Hub
    Exec --> Actions
    Exec --> FSMs
    Exec --> Retry
    Exec --> Reasoning
    Actions --> Isolation
    Reasoning --> Expressions
    Isolation --> Store
    Expressions --> Store

DAG for scheduling, FSM for lifecycle, event sourcing for persistence. For the full directory structure, request lifecycle, state machines, database schema, and design trade-offs see [docs/architecture.md](docs/architecture.md) and [docs/design-rationale.md](docs/design-rationale.md).

MCP Tools

OPCODE exposes six MCP tools over SSE:

| Tool | Purpose | | ---------------- | ------------------------------------------------------- | | opcode.run | Execute a workflow from a registered template | | opcode.status | Get current state of a workflow | | opcode.signal | Send signal to a suspended workflow (resolve decisions) | | opcode.define | Register a reusable workflow template (auto-versioned) | | opcode.query | Query workflows, events, or templates with filtering | | opcode.diagram | Generate visual DAG (ASCII / Mermaid / PNG) |

Agents identify themselves via agent_id in every call — auto-registered on first contact. For full parameter tables, filter fields, and mcporter connection details see [docs/mcp-tools.md](docs/mcp-tools.md).

Workflow Diagrams

OPCODE generates workflow DAG visualizations in three formats. The opcode.diagram tool and the web panel both use the same internal/diagram engine.

Mermaid

Flowchart syntax with status-colored nodes, renderable in GitHub, web UIs, and the panel:

graph TD
    __start__(("Start"))
    fetch_data["fetch-data"]
    validate["validate"]
    decide{{"decide"}}
    process["process"]
    notify["notify"]
    __end__(("End"))
    __start__ --> fetch_data
    process --> notify
    fetch_data --> validate
    validate --> decide
    decide --> process
    notify --> __end__

    classDef completed fill:#2d6a2d,stroke:#1a4a1a,color:#fff
    classDef failed fill:#8b1a1a,stroke:#5c0e0e,color:#fff
    classDef running fill:#1a5276,stroke:#0e3a52,color:#fff
    classDef suspended fill:#b7791a,stroke:#8a5c14,color:#fff
    classDef pending fill:#6b6b6b,stroke:#4a4a4a,color:#fff
    classDef skipped fill:#4a4a4a,stroke:#333,color:#aaa,stroke-dasharray:5 5
    class fetch_data completed
    class validate completed
    class decide suspended
    class process pending
    class notify pending

PNG (Graphviz)

Rendered locally via goccy/go-graphviz — no external services. Returned as base64-encoded PNG by the MCP tool.

Node shapes encode step type: rectangles for actions, diamonds for reasoning/conditions, circles for start/end. Colors indicate runtime status: green (completed), red (failed), blue (running), amber (suspended), gray (pending).

ASCII output is also available for CLI agents and terminal display — see [docs/architecture.md](docs/architecture.md#ascii-diagram-format) for examples and status tags.

Web Panel

OPCODE includes a built-in web management panel served on the same port as the MCP SSE endpoint (default :4100). No additional configuration is needed — browse to http://localhost:4100 when the daemon is running.

Stack

• Go html/template with embedded static assets (embed.FS)
• htmx for dynamic partial updates without page reloads
• Pico CSS (dark mode) with custom panel styles
• mermaid.js for client-side Mermaid diagram rendering
• SSE for live event streaming (EventHub → browser)

Pages

| Page | Description | | ------------------- | ----------------------------------------------------------------------- | | Dashboard | System counters, per-agent overview table, pending decisions, activity | | Workflows | Filterable workflow list (by status, agent), pagination | | Workflow Detail | Live DAG diagram, step states table, events timeline, cancel button | | Templates | Template list, create via JSON paste (auto-versions), definition viewer | | Template Detail | Version selector, Mermaid diagram preview, definition JSON | | Decisions | Pending decision queue with resolve/reject forms | | Scheduler | Cron job list, create/edit/delete, enable/disable toggle | | Events | Event log filtered by workflow and/or event type | | Agents | Registered agents with type and last-seen timestamps |

Live Updates

The dashboard and workflow detail pages receive real-time updates via SSE. The panel subscribes to the EventHub and pushes events to the browser as they occur — no polling.

Workflow Basics

A workflow is a JSON object with steps expressed as a DAG:

{
  "steps": [
    {
      "id": "fetch_data",
      "action": "http.get",
      "params": { "url": "https://api.example.com/data" },
      "timeout": "30s"
    },
    {
      "id": "transform",
      "action": "http.post",
      "depends_on": ["fetch_data"],
      "params": {
        "url": "https://api.example.com/process",
        "body": "${{steps.fetch_data.result}}"
      }
    },
    {
      "id": "review",
      "type": "reasoning",
      "depends_on": ["transform"],
      "config": {
        "prompt_context": "Review the processed data and decide next action",
        "options": [
          { "id": "approve", "des

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rendis](https://github.com/rendis)
- **Source:** [rendis/opcode](https://github.com/rendis/opcode)
- **License:** MIT

Install and usage instructions live in the source repository linked above.