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 · Playground · Language on one page · BPMN symbols · Report an issue

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), Tok (Julia General registry), tok for VS Code (Visual Studio Marketplace and Open VSX).

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 Tok.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

Tok.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(["Tok", "tok_jll"])    # or Pkg.add(url="https://github.com/tok-lang-bpm/tok", subdir="julia/Tok.jl")
using Tok
text = read("model.tok", String)
Tok.Engine.check(text)                                  # the engine: every layer of the language
m = Tok.Sim.model(text)                                 # native simulation (julia -t auto)
e = Tok.Sim.experiment([m, Tok.Sim.scenario(m; name="+1", resources=Dict("staff" => 3))]; replications=200)
Tok.Sim.summarize(e)
f = Tok.Fit.fit(text, Tok.Fit.read_xes("log.xes"))      # calibration on an event log
Tok.Fit.apply(text, f)                                  # the document with the fitted parameters

The engine library is found through TOK_LIBTOK, the package tok_jll, or the repository build (cargo build --release -p tok-capi); see docs/julia.md.

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

Repository

tools/check.sh runs every check of a release (Rust, Python, R and Julia tests, engine wheel and its parity with the Python implementation, the native tok program, the C library of the engine, the language and MCP servers, the VS Code extension and the playground) on Linux, macOS or Windows with Git Bash.

The BPMN validation comes from the bpmn.py validator used in the course Modelowanie procesów informacyjnych (Jagiellonian University), shipped here as tok.bpmnlib; its rule messages are in Polish and tok adds English equivalents. The diagram layout and SVG rendering started as a port of bpmn.py and, from 0.4, are developed in the Rust engine (rust/tok-bpmn), in the same style: left to right, pools stacked, lanes as rows.

Contributing and issues

Report problems and ideas in the issues of the GitHub repository. How to build, test and propose changes: CONTRIBUTING.md. Security problems: SECURITY.md. To cite tok, use CITATION.cff; the releases are archived on Zenodo, doi:10.5281/zenodo.23769633 (all versions).

License

GNU General Public License v3.0 or later, see LICENSE.