# Opcode > Zero-token execution layer for AI agents — define workflows once, execute forever. DAG engine with reasoning nodes, event sourcing, scheduling, and secret vault via 6 MCP tools over SSE. - **Type:** MCP server - **Install:** `agentstack add mcp-rendis-opcode` - **Verified:** Pending review - **Seller:** [rendis](https://agentstack.voostack.com/s/rendis) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [rendis](https://github.com/rendis) - **Source:** https://github.com/rendis/opcode ## Install ```sh agentstack add mcp-rendis-opcode ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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 ```bash git clone https://github.com/rendis/opcode.git go build -C /path/to/opcode -o opcode ./cmd/opcode/ ``` ### 2. Run the Server ```bash opcode install --listen-addr :4100 --vault-key "my-secret-passphrase" ``` This writes `~/.opcode/settings.json`, downloads [`mermaid-ascii`](https://github.com/AlexanderGrooff/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: ```bash 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`): ```json { "mcpServers": { "opcode": { "type": "sse", "url": "http://localhost:4100/sse" } } } ``` ### 4. Verify (optional) ```bash 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](https://skills.sh) ```bash npx skills add https://github.com/rendis/opcode --skill opcode ``` ### Install via [ClawHub](https://clawhub.ai) ```bash 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 ```mermaid 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: ```mermaid 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: ```json { "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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-rendis-opcode - Seller: https://agentstack.voostack.com/s/rendis - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.