graphedit

Graphedit is an application for visualising, creating, editing and debugging graph-based languages.

All graphs boil down to vertices and edges - plugins provide the syntax rules, the visual representation of the elements and the language smarts: language servers that analyze models and highlight problems while you edit.

This is the C++/Qt edition of Graphedit (originally written in Java/JavaFX).

Screenshot

Features

• Edit models of graph languages on a canvas: create, connect, move, copy and paste, with grid snapping and zooming. Editor tabs are split next to and below each other (also several views of one model) and dragged between groups and windows.
• A command palette (Ctrl+Shift+P) that finds every command, panel and model with a fuzzy search.
• An undo tree: undoing and editing again keeps the undone changes on a branch that you can return to.
• Syntaxes for labelled transition systems (LTS), Petri nets and simple graphs, with their rules and their own looks.
• Language servers: separate programs that analyze models and report diagnostics, which are highlighted on the canvas. They speak a JSON-RPC protocol modelled after the language server protocol.
• Projects with search, run targets, import from and export to TAPAAL, and the files of graphedit 1.x.
• Plugins for syntaxes, language servers, importers, exporters, views and side panels, built in this repository or outside of it.
• Made for AI agents as well: the agent api inspects and edits projects with the same rules (and undo) as the editor, from the command line (graphedit-cli), as a Model Context Protocol server, or inside the running editor, where the user sees every change. The agent panel of the editor is a chat with Claude Code or GitHub Copilot CLI that works on the open project this way.

Build

Requirements: a C++20 compiler with std::format (e.g. GCC 13+), CMake 3.25+, Ninja and Qt 6.5+ (Core, Network, Gui, Widgets, Svg and Test). Development happens with GCC 16, Clang 22 (clang-format and clang-tidy) and Qt 6.11. CMake and Ninja can also be installed with mise (mise install).

cmake --preset debug          # configure (see CMakePresets.json for the other presets)
cmake --build --preset debug  # build
ctest --preset debug          # run the tests

scripts/ci.sh runs the complete verification pipeline: formatting, a strict build, the tests, the example plugin, the package and clang-tidy. The docker directory has container images for it.

Install

cmake --workflow --preset release    # configure, build and test the release build, then package it with cpack
build/release/graphedit-*.sh --prefix="$HOME/.local" --exclude-subdir --skip-license

The packages are in build/release: an archive (graphedit-<version>-<system>.tar.gz) and the same as a self-extracting installer (.sh, see --help). The installation can be moved anywhere, since graphedit finds its libraries, plugins and language servers relative to its executables. It contains the editor (with a desktop entry), graphedit-cli, the standard plugin and what is needed to build plugins. Qt is not included: the system's Qt 6.5+ (Core, Network, Gui, Widgets and Svg) is used. Without packaging, a build can also be installed directly: cmake --install build/release --prefix ~/.local.

Packages for other systems are built (and tested there) with scripts/package-dist.sh, which needs neither root nor containers: the Debian packages for Ubuntu 24.10 with scripts/package-dist.sh ubuntu-24.10, and the installer for Windows (and a ZIP archive), which contains Qt, with scripts/package-dist.sh windows (see Packaging).

Usage

graphedit [project]                  # the editor (a project file, or a directory containing one)
graphedit-cli init my-project        # create a project
cd my-project
graphedit-cli call model.create model=lts.json syntax=LTS
graphedit-cli call vertex.add model=lts.json 'properties:={"name": "idle", "initial": true}'
graphedit-cli validate               # syntax rules and the diagnostics of language servers
graphedit-cli mcp                    # serve the agent api to AI agents (Model Context Protocol)

examples/projects/traffic is a project to try things with.

Documentation

Document	Contents
Architecture	How the pieces fit together
File formats	Projects, models and settings
Plugins	Writing syntaxes, language servers, views and panels
Design	The look of the editor: colors, type, spacing and components
Language server protocol	The protocol between the editor and language servers
Agent api	graphedit-cli, the Model Context Protocol server and the methods
Debugging	Debugging models in the editor, and the debug protocol
Packaging	The packages and how they are built and tested
AGENTS.md	Guidelines for working on the code (humans and AI agents)

Repository layout

Directory	Contents
src/core	graphedit-core: everything that does not need a display (Qt Core and Network)
src/gui	graphedit-gui: the graphical editor (Qt Widgets)
src/app	the graphedit executable
src/cli	the graphedit-cli executable
plugins/std	the standard plugin: syntaxes, TAPAAL import and export, views and panels
servers/lts-language-server	graphedit-lts-ls: the language server for labelled transition systems
examples	an example project and a plugin that is built outside of the repository
tests	the tests (QtTest)
docs	documentation
cmake, scripts, docker	build helpers, developer scripts and container images
packaging	the files of the packages for other systems (see Packaging)

Differences from graphedit 1.x

• Language servers speak a JSON based protocol over stdio instead of gRPC.
• Lua scripting is not available.
• Graphical and headless plugins are separate (graphical plugins declare "gui": true), so that syntaxes and language servers work in the command line interface too.

License

MIT, see LICENSE.