tok

tok

tok is a plain-text language for process models. One short text file describes a BPMN 2.0 process — pools, lanes, events, tasks, gateways, flows and data — together with the DMN decisions it uses, the forms people fill in and the parameters needed to simulate it. The tok tool checks the model and turns it into everything else: BPMN 2.0 XML with an automatic diagram layout (opens in Camunda Modeler and bpmn.io), SVG pictures, DMN files, Camunda forms and simulation results.

[The guide](https://tok-lang-bpm.github.io/) · [Playground](https://tok-lang-bpm.github.io/playground/) · [Language on one page](https://github.com/tok-lang-bpm/tok/blob/main/docs/cheatsheet.md) · [BPMN symbols](https://github.com/tok-lang-bpm/tok/blob/main/docs/symbols.md) · [Report an issue](https://github.com/tok-lang-bpm/tok/issues)

tok 1.0 "Interlibrary loan"

pool library "University library" lane reader "Reader" start need "Book needed" user order "Place an order" lane librarian "Librarian" user catalogues "Search the catalogues" xor available "Available locally?" user point "Point to the copy" send request "Order from another library" message="Order" end pointed "Copy pointed out" end ordered "Order placed"

pool other "Lending library"

flow need -> order -> catalogues -> available flow available -> point "yes" flow available -> request "no" flow point -> pointed flow request -> ordered

message request -> other "Order"

Start here

The tok project

Packages: tok-lang (PyPI), tok-cli, tok-core, tok-bpmn, tok-sim, tok-lsp, tok-mcp (crates.io), tokr (CRAN, and R-universe), TokLang (Julia General registry), tok for VS Code (Visual Studio Marketplace and Open VSX).

Who it is for

tok is for process analysts and information managers who keep models as documents, for teachers and students of process modelling, for developers of executable processes on Camunda 8, and for researchers who need a process-model format that can be written, checked and compared as text, for example in studies of process modelling with language models.

Why a text language

• Readable and reviewable. Every line starts with a keyword and describes one element. Changes show up as clear diffs in version control.
• Made for people and for AI agents. The whole language fits on one page (tok cheatsheet). An agent can write a model, run tok check --json (or call the check tool of the MCP server, tok mcp), read the line-numbered diagnostics and fix them, without ever touching XML or coordinates.
• Standards on the outside. tok is a notation for BPMN 2.0 and DMN, not a replacement. Everything you write is exported to the OMG formats that modelling tools and process engines read; tok import converts existing BPMN and DMN files back to text.
• Executable and measurable. The same file can carry the details Camunda 8 needs to run the process, and the times, resources and probabilities a simulation needs to estimate cycle times and workloads.
• Simple to implement. A line-based grammar with six token types. Python, Rust and Julia implementations pass the same conformance corpus byte for byte.

Install

The tok command is the Rust engine. It comes with the Python package tok-lang (Python 3.8 or newer; wheels for Windows x64, Linux x86_64 and aarch64, macOS; on Windows use py -m pip if pip is not on the path):

pip install tok-lang

tok --version

On a platform without a wheel pip builds the engine from the source archive, which needs Rust 1.99 or newer. The command alone, from crates.io or from a checkout of the repository:

cargo install tok-cli                 # the program tok

cd rust && cargo build --release -p tok-cli # target/release/tok

Every way reads every version of the language, 0.1 to 1.0. The package also keeps the pure-Python implementation frozen at language 0.3, the reference of the parity tests: TOK_ENGINE=python tok … runs it (docs/python.md).

The package also runs the MCP server for AI agents: tok mcp (docs/mcp.md). The R package tokr (install.packages("tokr")), the Julia package TokLang.jl (below), the language server tok-lsp and the MCP server as a program of its own (cargo install tok-lsp tok-mcp) and the VS Code extension *tok* are described under Tools.

Julia

TokLang.jl gives the whole language to Julia through the C interface of the engine, keeps an independent implementation of the core of the specification, and adds a native simulator for large experiments and the calibration of simulation parameters on event logs:

using Pkg; Pkg.add("TokLang")                 # or Pkg.add(url="https://github.com/tok-lang-bpm/tok", subdir="julia/TokLang.jl")

using TokLang text = read("model.tok", String) TokLang.Engine.check(text) # the engine: every layer of the language m = TokLang.Sim.model(text) # native simulation (julia -t auto) e = TokLang.Sim.experiment([m, TokLang.Sim.scenario(m; name="+1", resources=Dict("staff" => 3))]; replications=200) TokLang.Sim.summarize(e) f = TokLang.Fit.fit(text, TokLang.Fit.read_xes("log.xes")) # calibration on an event log TokLang.Fit.apply(text, f) # the document with the fitted parameters

The engine library comes with the package, through its dependency tok_jll; see docs/julia.md and the API reference.

Use

tok check model.tok              # diagnostics; --lang pl for Polish, --json for programs

tok fmt model.tok -w # canonical form tok bpmn model.tok # model.bpmn with diagram layout tok svg model.tok # model.svg tok export model.tok -o out/ # BPMN, SVG, DMN and forms (executable models for Camunda 8) tok import diagram.bpmn # BPMN 2.0 XML to tok tok sim model.tok --seed 1 # simulation indicators; --log log.csv for the event log tok eval model.tok DECISION a=1 # evaluate a decision

Tools

cd rust

cargo build --release -p tok-lsp -p tok-mcp # target/release/tok-lsp, target/release/tok-mcp bash tools/playground.sh # the playground in rust/target/playground

Documentation

| docs/feel.md | FEEL: the subset of languages 0.1–0.6 and the full FEEL of lang