KKSS — Keep Kratos Simple Stupid

A cross-platform desktop application for pre- and post-processing Kratos Multiphysics simulations, built with Electron on top of two proven VS Code extensions. Their viewer bundles are embedded as git submodules; workflow contracts are maintained upstream on dedicated integration branches:

Mode	Engine (submodule)	What it does
🔷 Pre-Processing	CAD-Preview (cad/)	STEP/IGES/BREP + STL/OBJ/PLY/glTF/3MF/AMF/USD/VRML/FBX + Collada .dae + OpenSCAD .csg/.scad viewing (no install — a bundled WebAssembly build evaluates .scad, see the OpenSCAD walkthrough) (plus VTK/MED/CGNS/Exodus/XDMF/MDPA and OpenFOAM cases imported as boundary surfaces via meshio++, and since meshio++ 17.3.0 also Kratos CAD JSON .cad.json, libMesh .xda/.xdr, and the .plt/.xplt/.meshb/.t19/.fil/.rst/.d3plot/.op2 solver-result imports and export targets), blank-model authoring from scratch, part definition, parametric geometry editing with live operation preview and query-pinned operands, a macro library, saved meshing presets, view bookmarks and named construction planes, split view with cameras linked across tabs, measurement & mass properties with tolerance bands, printability checks (overhang, wall thickness, build-plate fit) and the Draft analysis panel (draft and undercut facts along a pull direction, coloured in the view), mesh repair (fTetWild), promote-to-B-rep and Fit to CAD (meshio++'s fitCad turns a clean closed skin into an exact analytic B-rep — planes/spheres/cylinders/cones/tori, fillets, blends, chamfers and threads — checked by OpenCASCADE and saved as a new STEP), IGA tooling over the exact NURBS of a .cad.json/STEP read (iga_sample/iga_refine/iga_evaluate), primitive recognition and region fitting, 2D drawing export (silhouette SVG/DXF, hidden-line technical drawings and optional hole callouts/centre marks), markup annotations, Gmsh and octree FE meshing with quality statistics, variable-radius fillets, MMG remeshing to a new .med, and MDPA/MED/CGNS/XDMF export with optional unit conversion
🔶 Post-Processing	VSCode-MDPA-Preview (mesh/)	MDPA/VTK inspection plus extended mesh formats via meshio++ (read/write support) (Gmsh, Abaqus, Nastran, UNV, SU2, Exodus, CGNS, MED, GiD postprocess, EnSight Gold, Triangle, OpenFOAM, …; since meshio++ 17.3.0 also STEP/IGES solid surfaces, glTF/GLB scenes, binary Medit , and // exports, with exports auto-fitted to a B-rep), split view with per-pane fields and cameras, combinable field modes (contour/isosurface/quiver/deformed shape) & time-series visualization, beam/sphere rendering and face-normal (inverted-element) checks, mesh quality, mesh-size, watertightness and field-integral analysis, a data table with CSV/XLSX export and field-value plots over time, 30+ mesh operations with undo/redo and a batch queue (smoothing, renumbering, partitioning, refinement, cropping, field calculator/gradient/Hessian, error estimation, signed distance, a named-variables panel with global reductions, field transfer, merging, MMG remeshing with expression-driven and anisotropic sizing, frozen entities and per-part size bounds), multi-point constraints maintained through every edit, Kratos case setup, tracked solver runs, time-series packing (XDMF plus its required HDF5 companion) and viewport recording via built-in problemtypes (incl. the Flowgraph node-editor)

The app opens on a home screen with one button per task; a toolbar toggle (and Ctrl+0 for Home) switches between the screens, and both viewers stay alive, keeping their loaded file, camera, and history. Home and Settings can check the manual and assistant simulation environments independently, while optional project studies persist under .kkss/project.json. Unavailable manual-run requirements disable the matching Run action in the mesh Problemtype panel and the guided queue; geometry browsing remains available. Previewed mesh → case → solve plans run through a persisted, restart-aware queue; CAD mesh exports and solver runs carry owner-scoped receipts for status, cancellation and restart reconciliation. Parameter sweeps create fresh study and run identities with per-row resume and retry controls; comparisons distinguish mesh sensitivity from solver-setting changes. Run reviews include versioned preparation/provenance, revision-checked generated inputs and result companions, mesh statistics/quality, solver thread allocations and solver-published convergence evidence for the five built-in problemtypes when available. Variant comparisons can report assumption-visible Richardson/GCI mesh-sensitivity estimates from revision-bound refinement metadata. Selected field quantities retain their units and exact result revisions; unsupported or incomplete diagnostics stay explicit. See guided simulation work. Also in the box:

Three worked Kratos cases—a cantilever, a lid-driven cavity, and a two-stage structural load—include actual solver-produced VTK results that you can open in KKSS.

The geometry-to-results tutorials add eleven workflows that start in CAD and finish in the Problemtype results viewer. All eleven are solver-verified, covering structural mechanics (static and eigenmodes), fluid dynamics (laminar and RANS turbulence), convection-diffusion, potential flow, shallow water, FSI, CoSimulation, a virtual wind tunnel and a two-fluid dam break (which needs a one-file alias for the stock solver wrapper, explained on its page). A companion AI simulation walkthrough shows the same cantilever driven through the chat tools.

Scientific plotting (Mesh Preview 5.1): a dockable Plots pane and standalone File → Scientific Plot Builder… overlay histories, regional quantities, profiles and CSV/TSV data. Twelve chart families, numerical analysis, saveable recipes, full-resolution CSV/provenance and PNG/SVG exports share the assistant's numerical tools. The plotting guide documents the builder with explicit units/time conventions; run a tutorial case and build plots from its VTK timeline in the app.

• Kratos jobs — a dedicated Jobs panel with active counts, progress, recent logs, cancellation, and reconnect recovery for Kratos MCP simulations. Runs continue independently of chat; see background jobs.
• AI assistant (Ctrl+Shift+L) — a chat sidebar where an LLM (Anthropic Claude, any OpenAI-compatible backend, OpenCode Zen or OpenCode Go on one shared key, a ChatGPT subscription through Codex, or a Claude subscription through Claude Code) drives CAD editing, meshing, case setup, and Kratos runs through the engines' MCP tool servers plus the kratos-mcp-server (project scaffolding, multi-stage orchestration, presets, ProjectParameters explain, Flowgraph interop, and worked-example resources). API keys are configured in the Settings menu and stored via the OS keychain; subscription providers use the official local tool's signed-in account. A tool call that changes files, starts a solve, or that KKSS has no policy for is shown to you with its arguments and approved in the transcript before it runs — read-only tools run silently. The sidebar's MCP manager adds your own stdio or HTTP tool servers (and a trusted project folder's .kkss/assistant/mcp.json); their tools ask until you mark them read-only; plain-text standing instructions, skills and /name prompt templates guide it without ever changing what a tool may do; and lifecycle hooks run your own commands around its tool calls and messages — they can refuse a call or make it ask first, never approve one (see assistant extensions). Conversations are saved as you go and survive a quit — the header's history button lists them (switch, rename, delete) and + (New conversation) archives the current one rather than discarding it. The same unified toolset can be exposed to an external MCP client — Claude Code, GitHub Copilot, Claude Desktop — over a localhost Streamable HTTP endpoint via Settings ▸ MCP Server (off by default, bearer-token protected); see Use your own MCP client for the one-line Claude Code and Copilot setup.
• Embedded terminal (Ctrl+` ) — a real PowerShell/$SHELL panel below the viewer for launching Kratos runs, powered by node-pty + xterm.js.

Documentation: https://loumalouomega.github.io/KKSS/ · Downloads: download page (GitHub Releases) — Linux x86-64/ARM 64, Windows x86-64/ARM 64, macOS Apple Silicon

If the assistant’s Kratos tools cannot start, the chat sidebar explains why and offers Install uv for KKSS or Retry. Installation is optional and app-local; it does not change your system PATH or require administrator privileges. CAD and mesh tools remain usable during setup. See the assistant setup guide.

Mesh tools include named selection sets, shared Properties editing, selection export and deletion, and line probes that follow the results timeline. Mesh Preview 5.10.0 also brings native multi-file Import Mesh, grouped exports with graphical fidelity/provenance reports, worker-traced streamlines with partial cancellation and tube styling, all-step boundary flow balance, per-pane display units, density-field pressure conversion and validated Fluid time stepping, cancellable extended-format reads, in-place saves for OpenFOAM cases, five plot presets, and a command line that runs any operation or action as text. Time-series packing supports both XDMF with its required HDF5 companion and PVD collections for changing meshes. Mesh Preview 5.14.0 on meshio++ 17.3.0 adds the mesh → CAD direction on top: a .step export auto-fits a closed triangle skin into a real B-rep with OpenCASCADE (the fitted solid lands beside the file as a .cad.json companion), STEP/IGES and glTF/GLB open as solid surfaces and scenes, mesh_derive gains exact igaRefine/igaSample over the NURBS patches a CAD read keeps, and the Solvers export group gains Marc .t19, FEBio .xplt and MAPDL .rst writers plus binary Medit .meshb. Mesh Preview 5.18.0 adds KaHIP partitioning (minimizes the edge cut, through the full meshio++ artifact), cancellable derived-mesh/partition workers, per-SubModelPart measures and transforms, formula selection seeds, a Volume view for dense regular lattices, and fitted-STEP skin-deviation reporting. Mesh Preview 5.20.0 adds selective field reads (fields on mesh_info/mesh_convert), geometry-first loading of large .mdpa models with fields staged on demand, and a timeline frame cache; CAD-Preview 3.29.0 opens USD, VRML and FBX files for display. Optimization workflows gain Export Optimized Geometry as CAD… (shape from a design-field frame, topology from a contoured density field) with the matching case_optimization_cad MCP tool. See the mesh guide. CAD-Preview 3.30.0 adds Fill Surface, Round Corner, open-profile sheets, an octree-mesh FE engine and B-rep free-boundary checks; Mesh Preview 5.22.0 adds octree/CAD-surface/generated meshes, patch segmentation and refinement, curved quadratic cells and translated monitor prompts (meshio++ 17.13.0).

How it works

Both extensions already separate a browser-side viewer bundle (whose only VS Code touchpoint is acquireVsCodeApi()) from thin vscode-coupled glue. KKSS loads the built viewer bundles unchanged behind a tiny shim and provides Electron equivalents of the glue: native dialogs, a vscode module shim for the reused mesh host code, custom kkss:///kkss-file:// schemes in place of asWebviewUri, and worker threads for the heavy WASM kernels (OpenCascade, Gmsh, MMG). Upstream extension improvements are inherited by bumping a submodule pointer. See the architecture guide for details.

Building from source

git clone --recurse-submodules https://github.com/loumalouomega/KKSS.git
cd KKSS
npm ci
npm run submodules:install
npm start          # build everything and launch
npm run dist       # package installers into release/

npm run smoke checks the core viewer workflows. After building, npm run e2e runs the full Electron acceptance suite (use xvfb-run -a npm run e2e on headless Linux), including editor, terminal, chat/MCP, cloud shutdown and session lifecycle checks. Keyboard scenarios cover document tabs and chat approvals; axe-core scans representative screens in English and Spanish across all four app themes. It uses temporary profiles and local service fixtures; no API keys, cloud accounts or Kratos installation are needed. Failure artifacts go to test-results/.

KKSS-owned controls are available in English and Spanish. Choose Settings → Language and restart to apply the change; the embedded CAD and mesh viewers retain their upstream interface language. Press F6 / Shift+F6 to move between visible app regions. Developers can run the opt-in fresh-process performance benchmark with npm run perf; it records launch, CAD and mesh samples without controlling filesystem caches. See the development guide for baseline and strict-comparison details.

See CONTRIBUTING.md for the development workflow, testing, and the submodule update procedure.

Run in a browser (Docker)

The unmodified app can also be streamed to a browser tab from a Docker container (Xvfb + noVNC, behind an authenticated gateway). Every release publishes a linux/amd64 + linux/arm64 image to GHCR and Docker Hub:

docker run -d -p 127.0.0.1:6080:6080 --shm-size=1g ghcr.io/loumalouomega/kkss:latest
# then open http://localhost:6080/ and sign in

Or build it yourself from a checkout with initialized submodules:

git submodule update --init --recursive
docker compose up --build     # then open http://localhost:6080/

See the web deployment guide for volumes, environment variables, and security caveats. For an offline preinstalled solver environment, releases also provide an amd64 <version>-kratos image variant with Python 3.12, Kratos 10.4.3, and the pinned Kratos MCP server and application wheels.

Licensing

KKSS is licensed AGPL-3.0-or-later (see LICENSE). It bundles the GPL-2.0-or-later licensed CAD-Preview engine — whose shipped WASM statically links Gmsh and OpenCASCADE — and the AGPL-3.0-or-later licensed VSCode-MDPA-Preview engine, whose Flowgraph problemtype embeds the AGPL-3.0-or-later @kratos-flowgraph/flowgraph node editor; every bundled GPL/AGPL component grants an "or later" option, which is why AGPL-3.0-or-later — not the AGPL-3.0-only this project carried until 2026-09-24 — is the correct license for the combined distribution.