Simulator.Company — Claude Code & Codex Plugin

Status: stable — released, actively maintained. Supported clients: Claude Code ≥ 1.x, Codex. Go 1.24+ required. macOS and Linux tested.

A plugin for Claude Code and Codex that connects the Simulator.Company platform to Claude via MCP (Model Context Protocol). Claude gets direct access to the Simulator REST API and domain knowledge to manage actors, graphs, forms, and financial accounts through natural conversation.

What it does

The plugin bundles a Go MCP server that exposes the full Simulator.Company public API as MCP tools and provides specialist skills that teach Claude the platform's entity model and common workflows:

Requirements

• Claude Code or Codex installed
• Go 1.24+ available in PATH (the MCP server runs via go run, no build step needed)

  brew install golang        # macOS
  sudo apt install golang    # Ubuntu/Debian
  

  Verify with go version.
• A Simulator.Company account

Installation

Claude Code

From the GitHub marketplace:

claude plugin marketplace add corezoid/simulator-ai-plugin
claude plugin install simulator@simulator

Or from a local clone:

git clone https://github.com/corezoid/simulator-ai-plugin
claude plugin marketplace add ./simulator-ai-plugin
claude plugin install simulator@simulator

Codex

From the GitHub marketplace:

codex plugin marketplace add corezoid/simulator-ai-plugin
codex plugin install simulator@simulator

Or from a local clone:

git clone https://github.com/corezoid/simulator-ai-plugin
codex plugin marketplace add ./simulator-ai-plugin
codex plugin install simulator@simulator

No build step, no extra setup. The MCP server starts automatically on first use.

Updating

claude plugin update simulator@simulator   # Claude Code
codex plugin update simulator@simulator    # Codex

Restart Claude Code / Codex after updating to apply the new version.

Authentication

Simulator runs on many environments (cloud, on-prem, local dev), so the first step is to
choose one. The set-environment tool takes a cloud preset — mw.simulator.company
(default) or sim.simulator.company — or a custom/local URL (host or full URL; /papi/1.0
is appended if omitted). It fetches that gateway's public config to derive the correct
OAuth account URL — the platform authenticates through the account system, and one account
may back several environments, so the auth URL is determined per gateway rather than fixed.
The chosen API base and account URL are saved to .env (SIMULATOR_API_BASE_URL,
ACCOUNT_URL). Switching environment later clears the token + workspace and requires a fresh
login.

Next Claude runs the login tool — your browser opens for OAuth2 sign-in against the chosen
environment's account URL and the token is saved. Claude then lists your workspaces with
getWorkspaces and lets you pick one by name; set-workspace (by name or accId)
saves the choice as WORKSPACE_ID. You never need to know the workspace id.

The token is saved to .env in your working directory (mode 0600) and reused on every subsequent session. When it expires, the login flow triggers again automatically.

You can also trigger login manually at any time:

log in to Simulator

Static token (optional)

If you prefer to manage the token yourself, set it in .env or export it before starting Claude Code or Codex:

export ACCESS_TOKEN=your_token_here

The static token takes priority over saved credentials.

Configuration

All values are read from a .env file in the current working directory at startup, and the login / set-workspace tools persist their results back to that file.

Usage

Once installed, just talk to Claude naturally:

Create a business process graph for customer onboarding with three steps:
Document Collection → Review → Approval. Add all steps to a layer.

Create a Car form template with fields: make, model, year, color, VIN.
Add financial accounts: purchase value (USD asset), maintenance costs (USD expense),
and a mileage counter (km).

Record a $450 maintenance transaction on the Toyota Camry actor.
Then show me all accounts and their current balances.

Search for all actors of form type "Task" on the "Main Process" layer.

Pull layer 1a2b3c4d-... to a local YAML, let me edit it, then push it back.

MCP Tools

The MCP server exposes a curated, typed tool set (~46 tools) scoped to the core
scenarios — forms, actors, accounts, transactions, graph building, applications/smart forms
— rather than the entire REST surface. Each tool maps to a backend operation by its
operationId; a drift gate keeps the set in sync with the live /papi/1.0 contract.

Curated API operations (one tool per backend operation):

Engine tools (multi-call workflows + client-side computation):

Architecture

Claude Code / Codex
  └── simulator MCP server (go run ./cmd/server --profile local|prod)
        ├── config      cloud presets + local / prod profiles (API base + account URL)
        ├── auth        set-environment (public config → account URL), login (OAuth2 PKCE → .env), set-workspace
        ├── tools       curated typed operations (forms, actors, accounts,
        │               transactions, graph, apps) — one tool per backend op
        ├── engines     pullGraphFile, pushGraphFile, compactGraphLayout,
        │               pruneLongEdges, getAllLayerPlacements, uploadActorPicture(Bulk), createChart
        └── apiclient   HTTP → Simulator /papi/1.0 (local :9000 or mw gateway)

The server exposes a curated, typed tool set declared in Go (not a generic spec passthrough);
a drift gate validates those declarations against the backend's papi-openapi.json. Skills
add the domain knowledge on top. For the full design — profiles, the tool registry, engines,
the drift gate, and the auth flow — see docs/ARCHITECTURE.md.

Simulator.Company Entity Model

Workspace (accId)
  ├── Forms          — templates defining actor structure and field types
  │     └── Actors  — instances (nodes in the business process graph)
  │           ├── Links        — directed edges connecting actors
  │           ├── Layers       — visual views with actor positions
  │           ├── Accounts     — financial/metric tracking (asset, expense, counter...)
  │           │     ├── Transactions  — credits and debits on a single account
  │           │     └── Transfers     — atomic movement between two accounts
  │           ├── Reactions    — comments, approvals, ratings
  │           └── Attachments  — file storage
  ├── Currencies     — units of value for accounts (USD, EUR, Km, Units...)
  ├── Account Names  — category labels for accounts
  └── Link Types     — categories for edges between actors

Skills reference

/simulator

Universal Simulator assistant. Knows the full platform model, all entity types, and common workflow sequences. Use this when you need guidance across multiple domains or want to explore what's possible.

/simulator-init

Environment setup assistant — runs login, picks a workspace, and saves credentials to .env. Use it the first time you connect to Simulator or when switching workspaces.

/simulator-graph

Specialist for graph structure operations:

• Create, update, search, and delete actors
• Create single or bulk links between actors
• Manage layers — add actors with positions, search by form or text, move between layers
• Traverse the graph — get linked actors, actor links, global layer membership
• Pull a whole layer to YAML, edit locally, push it back

/simulator-forms

Specialist for form template design:

• Create custom forms with typed fields (text, number, select, date, file, formula, reference)
• Define default account structures within forms (auto-created for every new actor)
• Work with system forms (Graph, Layer, Event, Script/CDU, Account, Currency, Transaction...)
• Update, version, and manage form status

/simulator-finance

Specialist for financial and metric tracking:

• Set up currencies and account name categories
• Create accounts of any type on actors (asset, liability, expense, income, counter, state)
• Record immediate or 2-step (authorize → complete/cancel) transactions
• Create atomic multi-account transfers
• Query balances, transaction history, and filter transfers

/simulator-charts

Specialist for dashboard charts and time-series visualisation on graph layers — builds
chart actors via createChart (dynamic actorFilter or explicit accounts mode).

Project structure

simulator-ai-plugin/
├── .claude-plugin/
│   ├── marketplace.json         # Claude Code marketplace listing (points to plugins/simulator)
│   └── plugin.json              # Claude Code plugin manifest (root-level install target)
├── .mcp.json                    # Root-level MCP server config (used when installed via marketplace)
├── .agents/
│   └── plugins/
│       └── marketplace.json     # Codex marketplace listing (points to plugins/simulator)
├── Makefile                     # build / vet / test / discovery / run-local / run-prod
├── CHANGELOG.md
├── CLAUDE.md                    # Repo guide for Claude Code (points to AGENTS.md)
├── AGENTS.md                    # Repo guide for coding agents (canonical)
├── docs/                        # Project / contributor documentation
│   ├── ARCHITECTURE.md          # Plugin & MCP-server architecture
│   └── INTEGRATION.md           # pong-server integration plan & status
├── public/                      # Generated AI-discovery artifacts (llms.txt, .well-known/skills/index.json)
└── plugins/simulator/           # Plugin root (CLAUDE_PLUGIN_ROOT for both Claude Code and Codex)
    ├── .claude-plugin/
    │   └── plugin.json          # Claude Code plugin manifest
    ├── .codex-plugin/
    │   └── plugin.json          # Codex plugin manifest
    ├── .mcp.json                # MCP server configuration (go run ./cmd/server)
    ├── mcp-server/              # Go MCP server source (see mcp-server/README.md)
    │   ├── cmd/server/          # entry point: profile → tools → stdio
    │   ├── cmd/gendiscovery/    # regenerate public/ discovery artifacts
    │   ├── go.mod / go.sum
    │   ├── internal/
    │   │   ├── config/          # local/prod profiles
    │   │   ├── apiclient/       # HTTP client (auth, accId, timeouts)
    │   │   ├── tools/           # curated typed tools + testdata (drift spec, eval)
    │   │   └── engines/         # graph sync, layout, prune, upload, chart
    │   └── app/auth/            # OAuth2 PKCE flow + .env credential storage
    ├── skills/
    │   ├── simulator/                      # Universal assistant skill
    │   │   ├── SKILL.md
    │   │   └── references/api-operations.md
    │   ├── simulator-init/                 # Environment setup skill
    │   ├── simulator-graph/                # Graph specialist skill
    │   ├── simulator-forms/                # Forms specialist skill
    │   ├── simulator-finance/              # Finance specialist skill
    │   └── simulator-charts/               # Dashboard charts specialist skill
    └── docs/                    # Plugin-shipped reference (referenced by skills)
        ├── entities/            # Entity reference docs
        └── user-flows/          # End-to-end walkthroughs

Local development

Run the plugin from this repo (developing it, or testing against a local pong-server),
not from the marketplace.

Requirements: Go 1.24+, and a backend — a local pong-server on http://localhost:9000
(profile local) or the public gateway (profile prod).

1. Pick the environment

Create plugins/simulator/mcp-server/.env:

SIMULATOR_PROFILE=local      # or prod

Running with the local profile (via SIMULATOR_PROFILE=local or --profile local) does
two things for development:

• the server starts pointed at a local pong-server on http://localhost:9000;
• set-environment additionally offers a local preset (localhost:9000) — i.e.
  set-environment(preset="local") works. In the default prod profile that preset is
  hidden, so end users are only offered the cloud gateways (mw / sim) and a custom URL.

login / set-workspace (and set-environment) write ACCESS_TOKEN / WORKSPACE_ID /
SIMULATOR_API_BASE_URL / ACCOUNT_URL back into this same file.

2. Connect it in Claude Code

Pick one way (don't combine — two would register the simulator server twice):

• Plugin dir (recommended for dev): start Claude Code pointing at the repo —

  claude --plugin-dir /Users/<you>/PJ/control/simulator-ai-plugin/plugins/simulator
  

  To run against the local backend, prefix the launch with SIMULATOR_PROFILE — the
  MCP server inherits it from the Claude Code process, so you don't have to edit .env:

  SIMULATOR_PROFILE=local claude --plugin-dir /Users/<you>/PJ/control/simulator-ai-plugin/plugins/simulator
  

  (This targets pong-server on :9000 and makes set-environment offer the local
  preset; without it the server defaults to the prod profile. An env var set this way
  wins over mcp-server/.env. Equivalently: put SIMULATOR_PROFILE=local in
  plugins/simulator/mcp-server/.env.)
• Local marketplace install:

  /plugin marketplace add /Users/<you>/PJ/control/simulator-ai-plugin/plugins/simulator
  /plugin install simulator@simulator
  /reload-plugins
  

• Project auto-load: simply opening this repo as your project loads the root
  .mcp.json (a project-scoped server) — approve it when Claude Code asks.

Verify with /mcp — you should see simulator ✓ with ~50 tools.

Avoiding conflicts with the installed (prod) plugin. If you also have the published
simulator@simulator plugin installed, it registers the same simulator MCP server
and the same skills — so two copies collide. While developing locally, disable the prod
plugin:

/plugin                       # toggle simulator@simulator OFF (or: claude plugin disable simulator@simulator)

Re-enable it when you're done. Disabling is the only clean option if you're testing the
skills (they reference tools by bare name, so with both active they'd drive whichever
server wins — usually prod, against the prod backend).

If you must run both at once (e.g. to call your dev tools explicitly via
mcp__simulator-dev__* while keeping prod for normal use), rename the server in the root
.mcp.json from simulator to simulator-dev so the MCP server names don't clash. The
prod backend vs your local backend stay separate anyway — each instance reads its own
.env (the installed plugin's dir vs plugins/simulator/mcp-server/.env).

3. Authenticate and choose a workspace

log in to Simulator          # OAuth in the browser → token saved to .env
which workspaces do I have?  # getWorkspaces → list by name
work in <workspace name>     # set-workspace(name=…) → saves WORKSPACE_ID

4. Restart after you change the plugin

Edited Go code, a tool, .env, .mcp.json, or a skill? Reload — no reinstall needed:

/reload-plugins

This kills and relaunches the Go MCP server (go run ./cmd/server), re-reading the source
and .env. Check /mcp again if a server shows as failed (see its Errors tab in
/plugin).

Run / test outside Claude Code

make run-local      # go run ./cmd/server --profile local
make run-prod       # against the public gateway
make test           # unit + scenario + drift + eval tests
make lint           # golangci-lint v2 (gosec clean; style backlog)
make eval           # behavioural eval, dry (needs ANTHROPIC_API_KEY)
make eval-live      # behavioural eval executing tools against the backend

Debugging

Run the server directly against a profile (it logs startup config and request errors to
stderr):

cd plugins/simulator/mcp-server
go run ./cmd/server --profile local

Tests cover config, the HTTP client, the curated tools (scenarios + -race), the backend
drift gate, and the eval scenarios:

go test ./...

Compatibility

Note: If your Go installation is older than the module's go directive, the toolchain manager will try to download a newer version from proxy.golang.org. In air-gapped environments set GOTOOLCHAIN=local and install a matching Go version manually.

Links

• Simulator.Company
• API Documentation
• Claude Code
• MCP Protocol

Contributing & support

• Contributing guide — layout, build/verify, conventions
• Code of Conduct
• Security policy — report vulnerabilities privately
• Open an issue

License

MIT © Simulator.Company (Corezoid)