Orca

Orchestrated State Machine Language — a two-layer architecture for reliable LLM code generation.

The core insight: LLMs generate flat transition tables reliably, but they struggle to guarantee topology correctness on their own. Orca separates program structure (state machine topology) from computation (action functions), then verifies the structure automatically before any code runs.

Machines are written in plain Markdown — a format LLMs can read and write natively.

What it looks like

markdown

# machine PaymentProcessor

## context

| Field       | Type    | Default |
|-------------|---------|---------|
| order_id    | string  |         |
| amount      | decimal |         |
| retry_count | int     | 0       |

## events

- submit_payment
- payment_authorized
- payment_declined
- retry_requested
- settlement_confirmed

## state idle [initial]
> Waiting for a payment submission

## state authorizing
> Waiting for payment gateway response
- on_entry: send_authorization_request

## state declined
> Payment was declined

## state settled [final]
> Payment fully settled

## transitions

| Source      | Event                | Guard      | Target      | Action           |
|-------------|----------------------|------------|-------------|------------------|
| idle        | submit_payment       |            | authorizing |                  |
| authorizing | payment_authorized   |            | settled     |                  |
| authorizing | payment_declined     |            | declined    |                  |
| declined    | retry_requested      | can_retry  | authorizing | increment_retry  |
| declined    | retry_requested      | !can_retry | settled     | record_failure   |

## guards

| Name      | Expression              |
|-----------|-------------------------|
| can_retry | `ctx.retry_count < 3`   |

## actions

| Name                       | Signature                                | Effect      |
|----------------------------|------------------------------------------|-------------|
| send_authorization_request | `(ctx) -> Context`                       | AuthRequest |
| increment_retry            | `(ctx) -> Context`                       |             |
| record_failure             | `(ctx) -> Context`                       |             |

## effects

| Name        | Input                              | Output                   |
|-------------|------------------------------------|--------------------------|
| AuthRequest | `{ order_id: string, amount: decimal }` | `{ token: string }`  |

The verifier checks this before anything runs: reachability, deadlocks, guard determinism, orphan declarations, and effect consistency.

Features

Language

States with [initial] / [final] markers, descriptions, on_entry / on_exit actions
Transitions as a flat table — the format LLMs generate most reliably
Guard expressions: comparisons, boolean logic, null checks
Hierarchical (nested) states
Parallel regions with all-final / any-final / custom sync strategies
Timeouts: timeout: 30s -> state_name
Ignored events: ignore: EVENT_NAME
Machine invocation: one machine calling another, with input mapping and completion events
Multi-machine files: multiple machines in one .orca.md separated by ---
## effects section: named I/O schemas for external side effects
Decision tables: co-located conditional logic without guard explosion — verified for completeness, consistency, and cross-machine reachability

Verifier

Reachability: every state is reachable from the initial state
Deadlock detection: every non-final state has an outgoing transition
Completeness: every (state, event) pair is handled or explicitly ignored
Guard determinism: multi-transition guards are mutually exclusive
Property checking: bounded model checking with BFS — reachable, unreachable, passes_through, live, responds, invariant
Cross-machine: cycle detection, child reachability to final state, input mapping validation
Effect consistency: ORPHAN_EFFECT (declared but unused) and UNDECLARED_EFFECT (referenced but not declared)
Decision table checks: completeness, consistency, redundancy, coverage gap, dead guards, DT-constrained reachability — see DECISION_TABLES.md

Compilers

XState v5 createMachine() config
Mermaid stateDiagram-v2

Runtimes (standalone — no XState dependency)

TypeScript (@orcalang/orca-runtime-ts)
Python (orca-runtime-python)
Go (orca-runtime-go)

All three runtimes share the same feature set: guard evaluation, action registration, event bus (pub/sub + request/response), timeouts, parallel regions, snapshot/restore, machine invocation, persistence, and structured logging.

Monorepo structure

server.ts

packages/
  orca-lang/       Core: parser, verifier, XState/Mermaid compiler, CLI
  runtime-ts/      TypeScript runtime
  runtime-python/  Python async runtime
  runtime-go/      Go runtime
  demo-ts/         Text adventure game (uses runtime-ts)
  demo-python/     Agent framework scenarios (uses runtime-python)
  demo-go/         Ride-hailing coordinator — 5 machines (uses runtime-go)
  demo-nanolab/    nanoGPT training orchestrator — 5 machines (uses runtime-python)
  mcp-server/      MCP server exposing Orca tools to Claude and other agents

Setup

bash

# TypeScript packages
pnpm install
pnpm build

# Python packages (runtime + demos, requires Python >= 3.11)
pnpm run setup:python

# Go packages
pnpm run setup:go
pnpm run build:demo-go

CLI

bash

cd packages/orca-lang

# Verify a machine
npx tsx src/index.ts verify examples/payment-processor.orca.md

# Compile to XState
npx tsx src/index.ts compile xstate examples/payment-processor.orca.md

# Compile to Mermaid
npx tsx src/index.ts compile mermaid examples/text-adventure.orca.md

# Convert legacy .orca to .orca.md
# npx tsx src/index.ts convert <path-to-legacy.orca>

Language features

Parallel regions

markdown

## state processing [parallel]
> Payment and notification run concurrently
- on_done: -> completed

### region payment_flow

#### state charging [initial]
#### state paid [final]

### region notification_flow

#### state sending_email [initial]
#### state notified [final]

The machine transitions to completed when both regions reach their final state (all-final sync, the default).

Machine invocation

markdown

---

# machine OrderCoordinator

## state processing_payment
- invoke: PaymentProcessor
- on_done: payment_confirmed
- on_error: payment_failed

---

# machine PaymentProcessor

## state idle [initial]
## state settled [final]
...

The parent owns the child's lifecycle: starts it on entry, stops it on exit. The child's context is isolated from the parent's.

Timeouts

markdown

## state waiting_for_response
> LLM call in progress
- timeout: 30s -> timed_out

Snapshot and resume

All runtimes support saving and restoring machine state:

server.ts

// Save
const snap = machine.snapshot();
persistence.save('run-id', snap);

// Resume later (without re-running on_entry)
const snap = persistence.load('run-id');
await machine.resume(snap);

Structured logging

server.ts

import { MultiSink, FileSink, ConsoleSink, makeEntry } from '@orcalang/orca-runtime-ts';

const sink = new MultiSink(new ConsoleSink(), new FileSink('audit.jsonl'));

const m = new OrcaMachine(def, bus, {
  onTransition: (oldState, newState) => {
    sink.write(makeEntry({ runId, machine: def.name, from: oldState.toString(), to: newState.toString(), ... }));
  }
});

Using a runtime

TypeScript

server.ts

import { parseOrcaAuto, OrcaMachine, EventBus } from '@orcalang/orca-runtime-ts';

const def = parseOrcaAuto(source);
const bus = new EventBus();
const machine = new OrcaMachine(def, bus);

machine.registerAction('send_authorization_request', (ctx, event) => {
  return { ...ctx, payment_token: 'tok_123' };
});

machine.start();
machine.send({ type: 'submit_payment', payload: { order_id: 'ord_1', amount: 99.99 } });

Python

server.ts

from orca_runtime_python import parse_orca_auto, OrcaMachine, EventBus

def_ = parse_orca_auto(source)
bus = EventBus()
machine = OrcaMachine(def_, bus)

@machine.register_action('send_authorization_request')
async def send_auth(ctx, event):
    return {**ctx, 'payment_token': 'tok_123'}

await machine.start()
await machine.send({'type': 'submit_payment', 'payload': {'order_id': 'ord_1', 'amount': 99.99}})

Go

server.ts

import "orca-runtime-go/orca_runtime_go"

def, _ := orca_runtime_go.ParseOrcaAuto(source)
bus := orca_runtime_go.NewEventBus()
machine := orca_runtime_go.NewOrcaMachine(def, bus, nil, nil)

machine.RegisterAction("send_authorization_request", func(ctx map[string]any, event orca_runtime_go.Event) map[string]any {
    ctx["payment_token"] = "tok_123"
    return ctx
})

machine.Start()
machine.Send(orca_runtime_go.Event{Type: "submit_payment"})

Running the demos

bash

# Text adventure (TypeScript) — interactive CLI
cd packages/demo-ts && pnpm run cli

# Smoke test (non-interactive)
pnpm test:demo-ts

# Agent framework (Python)
pnpm run test:demo-python

# Ride-hailing coordinator (Go) — runs FareSettlement end-to-end
pnpm run test:demo-go
# With snapshot/resume:
cd packages/demo-go && ./trip --resume

# nanoGPT training orchestrator (Python, no torch required for tests)
pnpm run test:demo-nanolab

# nanoGPT training with PyTorch (GPU support)
# Install torch with GPU support, then run the full pipeline
.venv/bin/pip install torch torchvision torchaudio numpy requests
pnpm run run:demo-nanolab

Running tests

bash

# All TypeScript packages
pnpm test

# Core language only
pnpm test:lang

# Go runtime
cd packages/runtime-go && go test ./...

# Python runtime
cd packages/orca-lang && ../../.venv/bin/python -m pytest ../runtime-python/tests/ -v

# nanolab tests
pnpm run test:demo-nanolab

Test counts: 233 orca-lang · 63 runtime-ts · 87 runtime-python · 16 runtime-go · 47 demo-nanolab

Examples

All in packages/orca-lang/examples/:

File	Description
`simple-toggle.orca.md`	Minimal 2-state machine
`payment-processor.orca.md`	Guards, retries, effects
`text-adventure.orca.md`	Multi-state game engine
`hierarchical-game.orca.md`	Nested compound states
`parallel-order.orca.md`	Parallel regions with sync
`payment-with-properties.orca.md`	Bounded model checking properties
`key-exchange.orca.md`	Multi-machine: client/server key exchange protocol
`invocation-order.orca.md`	Multi-machine: order processing with child invocations
`saas-auth.orca.md`	SaaS authentication and registration flow
`health-check.orca.md`	Health check machine used by the dogfood runner
`simple-discount.orca.md`	Minimal standalone decision table
`payment-routing.orca.md`	Payment gateway router decision table
`shipping-rules.orca.md`	Shipping cost calculator decision table
`payment-with-routing.orca.md`	Combined machine + decision table

See DECISION_TABLES.md for a full guide to decision tables.

Skills & MCP setup

Orca ships six Claude Code skills backed by the @orcalang/orca-mcp-server MCP server. The skills call MCP tools directly — no shell or file access needed.

Skill	Trigger	What it does
`/orca-generate`	`<spec>`	Generate a verified machine from a natural language spec
`/orca-generate-multi`	`<spec>`	Generate a coordinated multi-machine system
`/orca-verify`	`[file]`	Verify a machine for errors and warnings
`/orca-refine`	`[file]`	Auto-fix verification errors using an LLM
`/orca-compile`	`[xstate\|mermaid] [file]`	Compile to XState TypeScript or Mermaid
`/orca-actions`	`[typescript\|python\|go] [file]`	Generate action scaffold stubs

Skills that use an LLM (/orca-generate, /orca-generate-multi, /orca-refine, and optionally /orca-actions --use-llm) call the MCP server, which calls your configured LLM provider. Skills that are purely structural (/orca-verify, /orca-compile, plain /orca-actions) never make LLM calls.

MCP server environment variables

Variable	Required	Description
`ORCA_API_KEY`	Yes	API key for your LLM provider
`ORCA_PROVIDER`	Yes	`anthropic`, `openai`, `ollama`, or `grok`
`ORCA_BASE_URL`	No	Override the provider's default base URL (for OpenAI-compatible APIs)
`ORCA_MODEL`	No	Model name (defaults to `claude-sonnet-4-6` for Anthropic)

Use ORCA_PROVIDER=openai with ORCA_BASE_URL for any OpenAI-compatible provider (MiniMax, Together, local vLLM, etc.).

Claude Desktop

Add the orca server to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

config.json

{
  "mcpServers": {
    "orca": {
      "command": "npx",
      "args": ["-y", "@orcalang/orca-mcp-server"],
      "env": {
        "ORCA_API_KEY": "<your-api-key>",
        "ORCA_PROVIDER": "anthropic"
      }
    }
  }
}

For an OpenAI-compatible provider (e.g. MiniMax):

config.json

{
  "mcpServers": {
    "orca": {
      "command": "npx",
      "args": ["-y", "@orcalang/orca-mcp-server"],
      "env": {
        "ORCA_API_KEY": "<your-api-key>",
        "ORCA_PROVIDER": "openai",
        "ORCA_BASE_URL": "https://api.minimaxi.chat/v1",
        "ORCA_MODEL": "MiniMax-M3"
      }
    }
  }
}

Restart Claude Desktop after editing. Skills in .claude/skills/ are discovered automatically when you open this repo.

Node.js version — Claude Desktop uses its own bundled Node.js, which may be older than the Node 18+ required by this package (ESM). If the server fails to start, add a PATH entry to env that puts your system Node's bin directory first — this is the most reliable way to ensure the right npx is found:
json
"env": {
  "PATH": "/usr/local/bin:/usr/bin:/bin",
  "ORCA_API_KEY": "..."
}
Run dirname $(which npx) to find the correct path. On nvm it will be something like ~/.nvm/versions/node/v22.x.x/bin.

Claude Code

Claude Code reads MCP server config from .mcp.json at the project root. This file is gitignored because it contains credentials — each developer creates their own.

Option A — use the published package (same as Desktop, no rebuild needed):

config.json

{
  "mcpServers": {
    "orca": {
      "command": "npx",
      "args": ["-y", "@orcalang/orca-mcp-server"],
      "type": "stdio",
      "env": {
        "ORCA_API_KEY": "<your-api-key>",
        "ORCA_PROVIDER": "anthropic"
      }
    }
  }
}

Option B — use the local build (recommended for development — changes take effect after rebuild):

config.json

{
  "mcpServers": {
    "orca": {
      "command": "node",
      "args": ["/absolute/path/to/orca-lang/packages/mcp-server/dist/server.js"],
      "type": "stdio",
      "env": {
        "ORCA_API_KEY": "<your-api-key>",
        "ORCA_PROVIDER": "anthropic"
      }
    }
  }
}

Build (or rebuild after changes):

bash

pnpm --filter @orcalang/orca-mcp-server build
# or from the package directory:
cd packages/mcp-server && npx tsc

Create .mcp.json at the project root (it is already in .gitignore), then restart Claude Code. Skills are auto-discovered from .claude/skills/ — no additional configuration needed.

Node.js version — Claude Code may use an older Node.js than the Node 18+ required by this package (ESM). If the server fails to start, add a PATH entry to env that puts your system Node's bin directory first:
json
"env": {
  "PATH": "/usr/local/bin:/usr/bin:/bin",
  "ORCA_API_KEY": "..."
}
Run dirname $(which npx) to find the correct path. On nvm it will be something like ~/.nvm/versions/node/v22.x.x/bin.

Background

Why "Orca"?

The name comes from Orchestrated (state machine language), but the whale was in mind too: orcas are highly coordinated, hunt in structured pods, and divide roles precisely — which maps well to a multi-machine system where a coordinator directs child machines through well-defined protocols.

Disambiguation: There is another project called Orca — a visual live-coding environment for sequencing MIDI and audio events, built by Hundred Rabbits. It's excellent, completely unrelated, and worth knowing about if you work in music or creative coding. This project is a different thing entirely: a state machine language for software orchestration.

Does this sidestep the halting problem?

Yes, deliberately — and that's the point.

The halting problem says you cannot decide in general whether an arbitrary program will terminate. That result applies to Turing-complete computations. Finite state machines are not Turing-complete: they have a finite, explicitly enumerated set of states and transitions declared upfront, with no unbounded loops or dynamic control flow in the topology itself. Reachability and deadlock analysis on an FSM is just graph traversal — it always terminates in O(states + transitions).

Orca's verifier exploits this by only verifying the topology layer — the state machine structure — where decidability is guaranteed. It does not attempt to verify the computation layer — the action functions you write inside each state. Those functions can be as complex as you like, and Orca makes no claims about them.

The practical consequence: the verifier can give you hard guarantees about your program's control flow (every state is reachable, no deadlocks, every event is handled, guards are mutually exclusive) without requiring your business logic to be formally specified. The two-layer separation is what makes this tractable. You get real structural correctness, scoped to the part of the program that can actually be checked.