semio

KO | EN

gitlite — search

#python #hacktoberfest #react #llm #android #machine-learning #java #windows #kubernetes #awesome-list #vue #pytorch #openai #ios

(★ 21)

💻 The right operating system for the left brain 🧠

semio Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<a href="https://docs.semio-tech.com">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="semio/assets/logo/logo_dark.svg">
 <source media="(prefers-color-scheme: light)" srcset="semio/assets/logo/logo.svg">
 <img alt="semio" href="https://github.com/usalu/semio/" src="semio/assets/logo/logo.svg">
 </picture>
 </a>
 
 <a href="https://play.semio-tech.com"><img src="semio/assets/badges/site-play.svg" alt="A free online playground to toy with semio without login."></a>
 <a href="https://docs.semio-tech.com"><img src="semio/assets/badges/site-docs.svg" alt="The documentation page to learn semio."></a>
 <a href="https://js.semio-tech.com"><img src="semio/assets/badges/dev-js.svg" alt="The elements Storybook for shared javascript UI elements."></a>
 <a href="https://discord.gg/m6nnf6pQRc"><img src="https://img.shields.io/discord/1338232508264747130?style=flat-square&color=ff344f" alt="Discord"></a>
 
 <a href="https://github.com/usalu/semio"><img src="semio/assets/badges/repo-semio.svg" alt="The repository."></a>
 <a href="https://doi.org/10.5281/zenodo.8419156"><img src="semio/assets/badges/cite-zenodo.svg" alt="Cite"></a>
 <a href="https://choosealicense.com/licenses/agpl-3.0/"><img src="semio/assets/badges/license-agpl-v3.svg" alt="Affero General Public License v3.0 or later"></a>
 
 <a href="https://eg-ice-25.semio-tech.com"><img src="semio/assets/badges/presentation-egice25.svg" alt="The presentation of our latest research paper on LLMs with semio."></a>
 <a href="https://doi.org/10.17868/strath.00093288"><img src="semio/assets/badges/latest-research.svg" alt="The latest research paper on LLMs with semio."></a>
 <a href="https://eg-ice-23.semio-tech.com"><img src="semio/assets/badges/presentation-egice23.svg" alt="The presentation of our previous research paper on formalizing architecture."></a>
 
 <a href="https://play.semio-tech.com"><img src="semio/assets/badges/ui-browser.svg" alt="Browser"></a>
 <a href="https://www.grasshopper3d.com/"><img src="semio/assets/badges/ui-grasshopper.svg" alt="Grasshopper"></a>
 <a href="https://www.microsoft.com/windows/windows-11"><img src="semio/assets/badges/ui-windows.svg" alt="Windows"></a>
 <a href="https://apple.com/macos"><img src="semio/assets/badges/ui-macos.svg" alt="macOS"></a>
 
 <a href="https://www.typescriptlang.org/"><img src="semio/assets/badges/powered-by-typescript.svg" alt="Typescript"></a>
 <a href="https://www.python.org/"><img src="semio/assets/badges/powered-by-python.svg" alt="Python"></a>
 <a href="https://learn.microsoft.com/en-us/dotnet/csharp/"><img src="semio/assets/badges/powered-by-csharp.svg" alt="C#"></a>
 
 
 🧩 Design-Information-Modeling for Kit-of-Parts 🏘

You want to 🧩 the next 🏘🏛🏢🏭🏫🏨⛪🕌 with 🤖? But 📐🔢🗣👥🖱️️⌨️️ takes all your ⌚? Then try to 🧠 the 🧬 and let semio 💉🖥✒🖨🪄🚀

# 👋 Hello contributor

> [!NOTE]
> Are you a user or new to semio? Then you might want to first check out our [docs](https://docs.semio-tech.com) 📖

Glad to see you!

Let me walk you through 🚶

# 📑 Overview

1. [🛍 Products](#%EF%B8%8F-products-)
   - [✏ sketchpad](#%EF%B8%8F-sketchpad-)
   - [👥 studio](#-studio-)
   - [☁ cloud](#%EF%B8%8F-cloud-)
   - [🤖 assistant](#-assistant-)
   - [🦗 semio.gh](#-semiogh-)
   - [🦏 semio.3dm](#-semio3dm-)
   - [🐝 semio.wasp](#-semiowasp-)
   - [🦌 semio.monoceros](#-semiomonoceros-)
   - [🐞 semio.ladybug](#-semioladybug-)
1. [🦑 Repo](#-repo-)
   - [⚖️ Principles](#-principles-)
   - [🏗️ Technologies](#-technologies-)
     - [👤 semio](#-semio-)
     - [🧰 repo](#-repo-)
     - [🔬 coda](#-coda-)
     - [🧩 elements](#-elements-)
   - [🔀 Git](#-git-)
     - [🦑 GitKraken](#-gitkraken-)
     - [🔍 ripgrep](#-ripgrep-)
     - [💬 Discord](#-discord-)
     - [📢 Release](#-release-)
     - [🏷️ Tag](#%EF%B8%8F-tag-)
     - [🌿 Branch](#-branch-)
     - [🗃️️ Commit](#%EF%B8%8F-commit-)
   - [🔀 Tools](#-git-)
1. [🧑💻 Development](#-development-)
   - [🖥️ Systems](#-systems-)
     - [🪟 Windows](#-windows-)
     - [🍎 macOS](#-macos-)
     - [🐧 Linux](#-linux-)
   - [🤖 AI](#-ai-)
     - [🛠️ Uses-Cases](#-uses-cases-)
       - [⚖️ Decision Making](#-decision-making-)
       - [🔁 Refactoring](#-refactoring-)
       - [🐛 Bug Fixes](#-bug-fixes-)
     - [⌨️️ Tools](#-tools-)
     - [🌐 Web-Chat](#-web-chat-)
       - [❄ ChatGPT](#-chatgpt-)
       - [🌟 Gemini](#-gemini-)
       - [AI studio](#-ai-studio-)
     - [💻 Editor](#-editor-)
       - [✈ Copilot](#-copilot-)
       - [🖱️️ Cursor](#-cursor-)
     - [🌊 Windsurf](#-windsurf-)
     - [⌨️️ CLI](#-cli-)
       - [⌨️️ Claude Code](#-claude-code-)
       - [🧾 Codex](#-codex-)
     - [☁ Cloud](#-cloud-)
       - [🦑 Jules](#-jules-)
     - [🔍 Agents](#-agents-)
       - [↕ Reorderer](#-reorderer-)
       - [🔁 Formatter](#-formatter-)
     - [🤖 Models](#-models-)
   - [🔄 CI/CD](#-cicd-)
1. [💯 Brand](#-brand-)
   - [✍ Concept](#%EF%B8%8F-concept-)
     - [✅ Do](#-do-)
     - [❌ Dont](#-dont-)
   - [🌈 Colors](#-colors-)
     - [🥇 Primary](#-primary-)
     - [🥈 Secondary](#-secondary-)
     - [🥉 Tertiary](#-tertiary-)
     - [⚫ Dark](#-dark-)
     - [⚪ Light](#-light-)
     - [🩶 Gray](#-gray-)
   - [📄 Typography](#-typography-)
     - [🔡 Typesetting](#-typesetting-)
   - [👀 Visual elements](#-visual-elements-)
1. [⚖️ License](#-license-)
1. [🔒Security](#-security-)
1. [✨ Contributors](#-contributors-)
1. [📊 Stats](#-stats-)

# 🛍 Products [↑](#-overview)

> Do you wonder how semio is interoperable? The reason is a shared [specification](#-requirements-) 🪢

## ✏ sketchpad [↑](#%EF%B8%8F-products-)

[sketchpad](#%EF%B8%8F-sketchpad-) is a simple-to-use, accessible and browser-based user interface for semio🖱️️

It is the digital pencil for sketching plans and digital scalpel for building models in semio ✍

![sketchpad demo](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/images/sketchpad-demo.gif)

## 👥 studio [↑](#%EF%B8%8F-products-)

A studio is a synchronous collaboriation environment for teams to work together in semio 🤝

![semio studio Demo](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/images/studio-demo.png)

## ☁ cloud [↑](#%EF%B8%8F-products-)

Use any file-hosting platform as an asynchronous Common-Data-Environment 📁

![Cloud Demo](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/images/cloud-demo.png)

## 🤖 assistant [↑](#%EF%B8%8F-products-)

The assistant helps you on every step in the design process with semio ✍

![semio assistant Demo](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/images/assistant-demo.png)

## 🦗 [semio.gh](https://docs.semio-tech.com/manuals/grasshopper) [↑](#%EF%B8%8F-products-)

A batteries-included [Grasshopper](https://www.grasshopper3d.com) plugin for semio ⚡

![semio Grasshopper Demo](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/images/grasshopper-demo.png)

## 🦏 semio.3dm [↑](#%EF%B8%8F-products-)

A Grasshopper-based integration of [Rhino](https://www.rhino3d.com) and semio 🔀

## 🐝 semio.wasp [↑](#%EF%B8%8F-products-)

A Grasshopper-based integration of [Wasp](https://www.food4rhino.com/en/app/wasp) and semio 🔀

![Wasp Demo](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/images/wasp-demo.png)

## 🦌 semio.monoceros [↑](#%EF%B8%8F-products-)

A Grasshopper-based integration of [Monoceros](https://monoceros.sub.digital) and semio 🔀

![Monoceros Demo](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/images/monoceros-demo.png)

## 🐞 semio.ladybug [↑](#%EF%B8%8F-products-)

A Grasshopper-based integration of [Ladybug](https://www.ladybug.tools) and semio 🔀

# 🦑 [Repo](https://github.com/usalu/semio) [↑](#-overview)

This git repo has everything that exists in the open semio ecosystem 🤯

## ⚖️ Principles [↑](#-repo-)

Let's start with the rules of thumbs that this codebase was built with 🫰

<details>
<summary>💾 If something can be written in a single file, then it probably should ✅</summary>

I know, the urge to tidy up or separate things is big 🗃️️

But try to withstand it 🫥

Out of my experience, it makes development slower, not faster 🐌

A single file is easier for humans and computers to understand 💡

You will be surprised

- by the awesome [fill-in-the-middle suggestions](#-cursor-) of your copilot 🤖
- by the hassle-free [context selection](#-browser-) for your ai agent 🖱️️
- by the smooth refactor experience by just going top-to-bottom ⬇
- by the beautiful diff for your next code review 🔍
- by the clean git-history when you try to find a certain change 🔁

</details>

<details>
<summary>🙃 Write and read code upside down ✅</summary>

Whenever something is referenced it should be above in the source code ⬆

This means that all the building blocks (functions, classes, components, …) are first defined and then used below ⬇

If you have a cyclic depedency (really?!) then put the object with lower complexity first 🥇

This means that when you start with unknown code, it is probably best to start on the bottom and go upwards 🖱️️

Why? LLMs, reflection, … , work best left-to-write 🤖

[But Fill-in-the-Middle training is for free!?](https://arxiv.org/abs/2207.14255)

Yeah, if you consider only FiM for code, then yes 🆗

But we want it all!

And is really so hard to start reading a from the bottom?

</details>

<details>
<summary>📑 If a class, function, component, … is only used once, then don't create it ❌</summary>

Probably, you learned to group code by classes, functions, components, … even if those definitions are only used once 🥇

It hides the actual complexity and makes it harder to navigate the code 🔍

</details>

<details>
<summary>📺 Inline everything that bearly fits onto the screen ✅</summary>

Smaller code, less tokens and easier diffs 🔍

Your [ai](#-ai-) bill will be lower and the completions will resolve faster 🚀

If you are not sure what the code does, you can ask [ai](#-ai-) 💬

</details>

<details>
<summary>🗣 Don't use comments or if you must, only tag code at the end of the line ❌</summary>

Smaller code, less tokens and easier diffs 🔍

Your [ai](#-ai-) bill will be lower and the completions will resolve faster 🚀

If you are not sure what the code does, you can ask [ai](#-ai-) 💬

</details>

<details>
<summary>📑 Use regions to structure your code ✅</summary>

Because you are not using classes, functions, components, … and you are inlining everything, your code will become long 📃

To organize your code, you can use nested regions 📂

In general, our files follow this structure:

1. Header
2. TODOs
3. Imports
4. Constants
5. CODE

</details>

<details>
<summary>📁 If a folder doesn't make your life dramatically easier, don't create it ❌</summary>

We all know this `./src/**` folder that has made it into a lot of starters 🚀

Other than feeling cool about using hacky abbreviations, does it really help you to understand the bundle faster and work more efficient on it?

If your bundle contains hundreds of config file and other bundle folders at the root, maybe 🤔

But most likely not ❌

</details>

<details>
<summary>📦 Parts that belong together should be close in the source code ✅</summary>

The default code organization is to group kind of structurally similar parts together 📂

All models next to each other, all controllers next to each other, all errors next to each other, …

While this pattern supports structural refactoring, it makes plain extensions harder because you have to search through all the files 🔍

Most changes are plain extensions and not structural refactors 🔄

Further it has the advantage that every LLM-agent only has to predict one big block of code instead of plenty of small ones 🤖

That's why frameworks like [React](https://react.dev/learn/thinking-in-react) exist or vendoring such as with [shadcn](https://ui.shadcn.com/docs) is more flexible than dependcenies such as with [bootstrap](https://getbootstrap.com/)

Cutting components vertically (a bit of logic with a bit of UI) instead of horizontally (all logic, all ui) requires more effort but enhances reusability 🔮

</details>

<details>
<summary>📄 If multiple people work longterm on the same part, then one file for each part should be created ✅</summary>

Trust me, it will make collaboration much easier 🔀

</details>

<details>
<summary>🔮 If you don't need an port because something is not likely to be extended soon, don't create it ❌</summary>

The main question is the port productive or not?

The pay-off of abstraction happens in the future 🛣

Every extension profits from a clean port 🚀

Most things are not extended 🪨

If you change your architecture, just design proper ports for something concrete not something potential and reactor it ✍

</details>

<details>
<summary>🤏 Repeating code is ok if it the repeated code is close in the source code ✅</summary>

We are past the time where we copy code for no reason 📃

Actually repeated code can improve the attribute of your copilots suggestion 🤯

The main question is how can your application grow?

If a change requires exponentially more duplication then you'll probably have to fix it 🛠️

If not, then you are probably good 👌

</details>

<details>
<summary>🏷️ Never use `type` for naming enums, ports, or types. Always use `kind` instead ✅</summary>

To avoid confusion with the native `type` concept in Semio, always use `kind` for naming enums, ports, or types that represent categories or classifications 🏷️

Examples: `ArtifactType` → `ArtifactKind`, `WindowType` → `WindowKind`, etc. 🔄

</details>

<details>
<summary>🤨 Wait, no high-level advice and only plain numbers, files, folders or close line of codes?</summary>

In our understanding, policy-of-thumbs are most useful when they are concrete 🔨

Besides that we are sure you know about KISS (Keep-It-Simple-Stupid), DRY (Dont-Repeat-Yourself) vs WET (Write-Every-Thing-Twice)/RUG (Repeat-Until-Good), YAGNI (You-Aren't-Gonna-Need-It), SoC (Separation-of-Concerns), Avoid Premature Optimization, Law of Demeter, LCHC (Low-Coupling-High-Cohesion), SOLID (SR (Single Responsibility), OC (Open/Closed), LS (Liskov's Substitution), IS (Port Segregation), DI (Dependency Inversion)), …

But as always, the devil is in the details 😈

Even if 95% of the codebase follows those principles, there are good reasons for the other 5% ⚖️

</details>

**🚩 Don't worry, you'll figure out the possibilities and make the right choice for the specific problems ✅**

## 🏗️ Technologies [↑](#-repo-)

The monorepo organizes its code into distinct technologies, each serving a specific domain in the ecosystem:

### [👤 semio](semio/README.md) [↑](#-technologies-)

The core design-information-modeling technology, containing the main schema, engines, and domain implementations.

### [🧰 repo](repo/README.md) [↑](#-technologies-)

Infrastructure and tooling for the monorepo, including CLI, vscode integrations, MCP servers, and generic utilities.

### [🔬 coda](coda/README.md) [↑](#-technologies-)

A research project introducing an AI-first design assistant, bridging the semantic graph with interactive UI.

### [🧩 elements](elements/README.md) [↑](#-technologies-)

Shared React UI components and layouts used across the browser-based applications within the monorepo.

## 🔀 [Git](https://github.com/usalu/semio.git) [↑](#-repo-)

### 🦑 GitKraken [↑](#-git-)

> [!NOTE]  
> It is free for open-source bundles like this one ❤

We use [GitKraken Desktop](https://www.gitkraken.com/git-client) as our git client 🖱️️

It is the only nice chronological graphical overview for **all** branches at the same time that we found 🔍

The devcontainer installs Linux GitKraken Desktop and bootstraps zero-touch local workspace config for the semio monorepo and its git submodules, so the default Semio workspace is ready after attach without manual repository grouping 🔀

### 🔍 ripgrep [↑](#-git-)

The devcontainer installs [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) for zero-touch codebase searching 🔎

It is the fastest way to find anything in this monorepo ⚡

### 💬 Discord [↑](#-git-)

Most git events are synchronized with our [repo channel](https://discord.com/channels/1338232508264747130/1339164626658525246) 💬

It is perfect to find the latest activities and the history 🔍

### 📢 Release [↑](#-gitstyle-)

Every release contains a set of matching [requirements](#-requirements-), [bundles](#-bundles-), [examples](#-examples-) and [docs](#-docs-) 📦

The release notes follow this format:

```
SYMBOL TITLE

COMPONENT
- SYMBOL SUMMARY [CONTRIBUTOR]
…
```

**Title symbols:**

- 🏗️️ Foundational work
- 🛠️ Heavy work
- 🪛 Minor work
- 🐛 Major Bug fix

**Description symbols:**

- 🌱 Started [not yet ready]
- ➕ Added [ready]
- ⬆ Updated
- 🔄 Renamed
- 🔁 Refactored
- 🐛 Bug fix

Before every [release](#-release-) the [repo](#-repo-) is archived 📦

### 🏷️ Tag [↑](#-gitstyle-)

We have two different types of tags:

- `rYY.MM-V` for [releases](#-release-) (e.g `r21.06-1`,`r23.07-2`,`r24.12-1`, `r25.07-1`, …)
- `COMPONENT-vMAJOR.MINOR.PATCH` for [bundles](#-bundles-) which follow the [semver](https://semver.org/) versioning scheme (e.g [`engine-v4.0.2`](#-semioengine-), [`sketchpad-v1.0.0`](#-semiodesktop-), [`grasshopper-v5.4.0-beta`](#-semiograsshopper-), …)

### 🌿 Branch [↑](#-gitstyle-)

The `main` branch is compressed (squashed history) and acts as the canonical integration branch 🗜

If a release receives updates after `main` already progressed, create a parallel `release/rYY.MM-V` branch for that release and keep it compressed as well 🧵

Every [contributor](#-contributor-) has their own `FIRSTNAME` general-purpose development branch 🛠️

In [GitKraken](#-gitkraken-) you will quickly find the latest development branch 👀

Other branches are created for [bundles](#-bundles-), [specific features](https://github.com/usalu/semio/labels/enhancement) or [bug fixes](https://github.com/usalu/semio/labels/bug) 🐛

Usually one person works on one feature at a time and hence the `-NAME` suffix 📛

### 🗃️️ Commit [↑](#-gitstyle-)

Commit messages follow this format:

```
MAIN-TASK-SYMBOL SUMMARY WORK-SYMBOL
```

The first symbol encodes the main task of the commit and the last symbol encodes the amount of work (`🪛` < `🔨` < `🛠️` < `🏗️️`) 🧰

<details>
<summary>📦 Commit as much as you like ✅</summary>

Are you worried about committing all those binary application files (`.zip`, `.gh`, `.blend`, `.glb`, `.3dm`, …) or the intermediate versions between your [ai](#ai) edits?

Well, normally you should be 💾

But as we archive and squash all commits on every [release](#-release-) nothing is lost or polluted 💯

</details>

<details>
<summary>⌛ Push around once an hour ✅</summary>

Pushing regularly keeps you extra safe from losing your work 🛟

There are a few services (like [Discord](https://discord.com/channels/1338232508264747130/1339164626658525246)) that are automatically updating to what happens in the [repo](#-repo-) 🔄

To keep our inbox notifications low, we try to push not more than once an hour ⬆

</details>

# 🧑‍💻 Development [↑](#-overview)

Different [ecosystems](#-ecosystems-) need different tools 🧰

## 🐳 Devcontainer (Recommended) [↑](#-development)

The recommended way to develop is using the devcontainer which provides a consistent cross-platform environment 🖥️

**Prerequisites:**

- [Docker Desktop](https://www.docker.com/products/docker-desktop/) or compatible container runtime
- [VS Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)

**Getting Started:**

1. Clone the repository
2. Open in VS Code
3. Click "Reopen in Container" when prompted (or run "Dev Containers: Reopen in Container" from command palette)
4. Wait for container build and setup to complete

The devcontainer includes:

- Node.js 24 LTS, Go 1.26, Python 3.14, .NET SDK 8.0/9.0/10.0, Rust 1.92
- All required VS Code extensions
- Pre-configured development environment
- Port forwarding for all dev servers (3000, 4000, 4321, 5678, 6006, 2507)

## 🪟 Windows Setup [↑](#-development)

Native Windows development is zero-touch through the checked-in bootstrap script:

```powershell
bun ./script.ts setup native
```

The script installs the same baseline toolchain the devcontainer provides on a fresh machine:

- Git, Git LFS, GitHub CLI, ripgrep, jq, SQLite
- Microsoft OpenJDK 21 and native Neo4j Desktop integration
- Node.js 24 LTS + npm 11.7, Go 1.26, Python 3.14, uv, rustup, .NET SDK 8/9/10
- GitKraken Desktop + CLI, F3D, VS Code + `code`
- Gemini CLI, TypeScript LSP, Pyright
- repo hooks, MCP client config, Python/Rust/Playwright setup, npm/uv dependencies, and the local repo VSIX

After the bootstrap completes, open a new terminal and use the same repo commands as in the devcontainer. The script also keeps `PLAYWRIGHT_BROWSERS_PATH` on the repo-local shared cache so Playwright downloads stay warm across runs.

Native Neo4j Desktop must own the local DBMS. Create a Neo4j Desktop **Local Instance** named `semio`, set the initial password to `password`, and start it. The repo setup then enables APOC on that DBMS, restarts it when needed, and configures/imports through Bolt without editing Desktop internals:

- URL: `bolt://127.0.0.1:7687`
- User: `neo4j`
- Password: `password`
- Browser: `http://127.0.0.1:7474`
- Database: `neo4j`

Native macOS and Linux use the same root router:

```bash
bun ./script.ts setup native
```

IDE startup runs `bun ./script.ts start`, which checks the native Neo4j Desktop `semio` DBMS at `bolt://localhost:7687`, verifies APOC, and attempts to create the product graph databases `semio`, `elements`, `coda`, and `reuse`, plus any names listed in **`NEO4J_EXTRA_GRAPH_DATABASES`** (comma-separated, e.g. `metabolism,mydb`), when the DBMS edition supports multi-database administration. **Neo4j Community Edition allows only one standard user graph per DBMS** (often still named `neo4j` until you rename it). Those `CREATE DATABASE` calls do nothing useful on Community, so you will **not** see extra graphs in Desktop or Browser unless the edition supports them. Use **Neo4j Enterprise** (or another deployment that supports multiple standard databases) if you need isolated Bolt databases for each graph.

**Where “databases” show up:** In Neo4j Browser, open your DBMS at `http://127.0.0.1:7474`, sign in, then use the **database dropdown** (next to the query editor). Only editions that support multi-database list more than one user graph besides `system`. To confirm what the server supports, run `SHOW DATABASES` while connected (Community typically shows `system` and one user database).

**Optional MCP graphs:** The **`neo4j-metabolism`** server runs `… mcp neo4j metabolism` (Bolt database `metabolism`, same argv pattern as the four product servers). For any other extra Bolt name without adding another MCP entry, set **`NEO4J_EXTRA_GRAPH_DATABASE`** and use **`neo4j-extra`** (it runs `… mcp neo4j` with no argv segments so `NEO4J_DATABASE` comes from that env). **`bun run generate`** uses **`NEO4J_EXTRA_GRAPH_DATABASES`** (plural, comma list) to include extra graphs in the APOC export loop alongside the four product graphs.

**If you use Enterprise and an extra graph is missing:** Connect to the `system` database and run `CREATE DATABASE <name> IF NOT EXISTS;` then `START DATABASE <name> WAIT;` (use backticks around `<name>` if it contains `-` or other special characters), and refresh the database list.

## 🪄 [AI](AGENTS.md) [↑](#-development-)

Most of our [codebase](#-principles-) is heavily optimized for AI agents 🤖

We pick tools based on billing model (request-based vs token-based), required context size, and whether a workflow needs MCP (e.g. Playwright) 🧰

## 🛠️ Uses-Cases [↑](#-ai-)

Here some strategic advice for different uses-cases 🗺

### ⚖️ Decision Making [↑](#-uses-cases-)

[Model](#-models-) will always tell you that your ideas, guesses, analysis, … are great 💯

This makes it really hard to use them for decision making because they tend to just reinforce your own bias 📢

Try to formulate everything as neutral, general and unbiased as possible 🕊

### 🔁 Refactoring [↑](#-uses-cases-)

Most refactors are too big to be done in one go and [models](#-models-) are usually steered that if they think the problem is too big then they try to automate it with scripting 🤖

This is usually not possible and then they fail ❌

After all from a provider perspective those tasks are dangerous and hard to scale and we understand why they want the model to avoid doing it 🔥

The next problem is that when they take the wrong approach then, due to large context, they hardely remember how the original state was 🤔

For this reason, we usually create a new file which we name with the suffix`*.old` and this way in the prompt we can refer to the original state 📄

### 🐛 Bug Fixes [↑](#-uses-cases-)

Try to describe only how to the bug appears and **not** what you think caused it 😶

Experience what can be causes for bugs is increadibly valuable skill as a developer but the problem is that [models](#-models-) are really biased the way you ask questions 🏋

Especially when your guess is wrong then the [model](#-models-) might have found the mistake but because of your bias it tries to take a different approach to fix it 🔀

Secondly, if the model can't find the bug then it will often try to remove functionality, add try catch blocks, add logging and other things that fastly turn your codebase into a mess 💣

Therefore, it is often a good idea that after you found the bug, reset your branch and create a new ticket where you define exactly how to fix the bug 🪛

## ⌨️️ Tools [↑](#-ai-)

### 🌐 Web-Chat [↑](#-tools-)

For research, prompt preparation or [single file-related](#-principles-) operations (sorting, formatting, explaining, …) we use the free , [Gemini](https://gemini.google.com) or [Groq](https://console.groq.com), … in the browser to not waste precious tokens 🆓

#### [❄ ChatGPT](https://chatgpt.com) [↑](#-web-chat-)

The free quota is very quickly reached but resets regularly and hence we just use it for questioning or prompt preparation 💬

#### [🌟 Gemini](https://gemini.google.com) [↑](#-web-chat-)

#### [AI studio](https://ai.google.com/studio) [↑](#-web-chat-)

Good for larger experiments due to more generous free quota 🥼

### 💻 Editor [↑](#-tools-)

#### ✈ [Copilot](.github/agents/semio.agent.md) [↑](#-ai-)

<details>
<summary>📚 Resources:</summary>

- [Chat modes](https://code.visualstudio.com/docs/copilot/chat/chat-modes)

</details>

Copilot is our default for most tickets because request-based billing makes fast interaction cheap 💳

#### 🖱️️ [Cursor](.cursor) [↑](#-ai-)

<details>
<summary>📚 Resources:</summary>

- [Rules](https://docs.cursor.com/context/rules)

</details>

We have the [Pro](https://www.anthropic.com/claude/pricing) plan 💳

We use [Cursor](https://www.cursor.com) as our main editor for typing code mostly with [Tab](https://docs.cursor.com/tab/overview) ➡

For tasks that require updated large docs that are too large to paste into the prompt, we use the agent 📚

But in general, we don't use the chat because it is way too expensive 💰

#### 🌊 Windsurf [↑](#-editor-)

Used for token-heavy test-driven-development workflows with MCP (especially Playwright) 🥼

### ⌨️️ CLI [↑](#-tools-)

#### ⌨️️ [Claude Code](CLAUDE.md) [↑](#-ai-)

We have the [Pro](https://www.anthropic.com/claude/pricing) plan 💳

Used for small bugs and focused fixes with strong repo context 🧠

#### 🧾 Codex [↑](#-cli-)

Used for simple tasks (small edits, small refactors, small doc updates) 🧩

The canonical root agent instructions live in `AGENTS.md`. Root aliases such as `CLAUDE.md` and `GEMINI.md` are recreated from that file when you run `bun ./script.ts setup git` (also invoked from `npm run setup`), using symlinks when the shell supports them and a hard-link fallback on restricted Windows shells.

Run `npm run setup` once after cloning for the full workspace bootstrap, or run `bun ./script.ts setup git` if you only need git symlink checkout, root alias files, and removal of any legacy repo-managed git hooks on Windows, macOS, and Linux. On Windows, true symlink creation may require Developer Mode or an elevated shell.

### ☁ Cloud [↑](#-tools-)

#### 🦑 Jules [↑](#-tools-)

[!NOTE] Free plan includes 15 tasks per day, 3 concurrent tasks and powered by Gemini 2.5 Pro 🚀

Used on the phone when no IDE is available 📱

### 🔍 Agents [↑](#-ai-)

#### ↕ Reorderer [↑](#-agents-)

Used to ensure consistent order of source code, docs, …

- [GitHub Agent](.github/agents/semio.agent.md)

#### 🔁 Formatter [↑](#-agents-)

Used to ensure consistent formatting of source code, docs, …

- [GitHub Agent](.github/agents/semio.agent.md)

### 🤖 Models [↑](#-ai-)

The default model for agent work is the one native to the platform we use for the agent 🧠

## 🔄 CI/CD [↑](#-development-)

<details>
<summary>📺 Channels:</summary>

- [TechWorld with Nana](https://www.youtube.com/@TechWorldwithNana) - `devops`

</details>

All automation, CI runs, and agent workflows are controlled through the canonical root commands `setup`, `start`, `dev`, `generate`, `lint`, `format`, `test`, `build`, `publish`, and `purge` (see root `package.json`). Only `dev` is intended to stay live for watch mode, while the remaining commands exit so CI and agents can finish reliably.
The root `package.json` uses Nx to orchestrate the command pipeline, and delegates bundle builds, tests, and publishing to Nx targets (`bun nx run …`).
Git hooks are not installed by this repo; run `bun run lint`, `bun run format`, and `bun run test` explicitly before pushing. `bun ./script.ts setup git` removes any legacy pre-commit or post-commit hooks that would block commits, rebases, or squashes.

# 🏘 [Examples](semio/examples) [↑](#-overview)

## 🚀 [Starter](semio/examples/starters) [↑](#%EF%B8%8F-examples-)

## 👋 [Hello semio](semio/examples/hello-semio) [↑](#%EF%B8%8F-examples-)

## 🌈 [Geometry](semio/examples/geometry) [↑](#%EF%B8%8F-examples-)

## 🫀 [Metabolism](semio/examples/metabolism) [↑](#%EF%B8%8F-examples-)

# 💯 Brand [↑](#-overview)

## ✍ Concept [↑](#-brand-)

### ✅ Do [↑](#%EF%B8%8F-concept-)

- Visual is better than text 👀
- Compact ➡ More information ➡ Faster to understand 🚀

### ❌ Dont [↑](#%EF%B8%8F-concept-)

- Rounded corners ⬜
- Shadows 🌤
- Multiple unicode directly after each other 🥇🥈🥉

## 🌈 Colors [↑](#-brand-)

![Palette](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/lists/palette.png)

| Name                                   | Hex     | RGB         | HSL              | HSV (or HSB)     | CMYK          | Color            |
| -------------------------------------- | ------- | ----------- | ---------------- | ---------------- | ------------- | ---------------- |
| Primary                                | #FF344F | 255, 52, 79 | 352, 100, 60.2   | 352, 79.6, 100   | 0, 80, 69, 0  | Folly            |
| Secondary                              | #00A69D | 0, 166, 157 | 176.7, 100, 32.5 | 176.7, 100, 65.1 | 100, 0, 5, 35 | Persian green    |
| Tertiary                               | #FA9500 | 250, 149, 0 | 34.8, 100, 49    | 35.76, 1, 0.49   | 0, 40, 100, 2 | Princeton orange |
| Dark (= 0)                             | #001117 |             |                  |                  |               |                  |
| Grey 100 (= 0.1 = 1/10)                | #06171C |             |                  |                  |               |                  |
| Dark 8-9 (= 0.1̅ = 1/9)                 | #07181D |             |                  |                  |               |                  |
| Dark-Dark-Dark-Grey (= 0.125 = 1/8)    | #091A1F |             |                  |                  |               |                  |
| Dark 6-7 (= 0.142857 = 1/7)            | #0C1C21 |             |                  |                  |               |                  |
| Dark-Dark-Grey (= 0.166667 = 1/6)      | #112025 |             |                  |                  |               |                  |
| Grey 200 (= 0.2 = 1/5)                 | #18272A |             |                  |                  |               |                  |
| Dark 7-9 (= 0.2̅ = 2/9)                 | #1D2B2F |             |                  |                  |               |                  |
| Dark Grey (= 0.25 = 1/4)               | #243235 |             |                  |                  |               |                  |
| Dark 5-7 (= 0.285714 = 2/7)            | #2E3C3D |             |                  |                  |               |                  |
| Grey 300 (= 0.3 = 3/10)                | #334041 |             |                  |                  |               |                  |
| Dark-Dark-Grey (= 0.3̅ = 1/3)           | #3E494A |             |                  |                  |               |                  |
| Dark-Grey-Grey-Grey (= 0.375 = 3/8)    | #4C5756 |             |                  |                  |               |                  |
| Grey 400 (= 0.4 = 2/5)                 | #555F5D |             |                  |                  |               |                  |
| Dark 4-7 (= 0.428571 = 3/7)            | #606966 |             |                  |                  |               |                  |
| Dark 5-9 (= 0.4̅ = 4/9)                 | #666E6B |             |                  |                  |               |                  |
| Grey (= 0.5 = 1/2)                     | #7B827D |             |                  |                  |               |                  |
| Light 5-9 (= 0.5̅ = 5/9)                | #91968F |             |                  |                  |               |                  |
| Light 4-7 (= 0.571429 = 4/7)           | #979B94 |             |                  |                  |               |                  |
| Grey 600 (= 0.6 = 3/5)                 | #A2A59D |             |                  |                  |               |                  |
| Light-Grey-Grey-Grey (= 0.625 = 5/8)   | #ABADA4 |             |                  |                  |               |                  |
| Light-Grey-Grey (= 0.6̅ = 2/3)          | #B9BBB0 |             |                  |                  |               |                  |
| Grey 700 (= 0.7 = 7/10)                | #C4C4B9 |             |                  |                  |               |                  |
| Light 5-7 (= 0.714286 = 5/7)           | #C9C8BD |             |                  |                  |               |                  |
| Light Grey (= 0.75 = 3/4)              | #D3D2C5 |             |                  |                  |               |                  |
| Light 7-9 (= 0.7̅ = 7/9)                | #DAD9CB |             |                  |                  |               |                  |
| Grey 800 (= 0.8 = 4/5)                 | #DFDDD0 |             |                  |                  |               |                  |
| Light-Light-Grey (= 0.8̅ = 5/6)         | #E6E4D5 |             |                  |                  |               |                  |
| Light 6-7 (= 0.857143 = 6/7)           | #EBE8D9 |             |                  |                  |               |                  |
| Light-Light-Light-Grey (= 0.875 = 7/8) | #EEEADB |             |                  |                  |               |                  |
| Light 8-9 (= 0.8̅ = 8/9)                | #F0ECDD |             |                  |                  |               |                  |
| Grey 900 (= 0.9 = 9/10)                | #F1EDDE |             |                  |                  |               |                  |
| Light (= 1)                            | #F7F3E3 |             |                  |                  |               |                  |

### 🥇 Primary [↑](#-colors-)

Use the primary color for the most important elements of your design 🏆

We use it e.g. for:

- Highlighting interactive elements 🖱️️
- Background for important elements 🟥

### 🥈 Secondary [↑](#-colors-)

### 🥉 Tertiary [↑](#-colors-)

### ⚫ Dark [↑](#-colors-)

### ⚪ Light [↑](#-colors-)

### 🩶 Gray [↑](#-colors-)

Are you curious how a 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 and 11 colored gradient can come together for an invertible theme in a semantically meaningfull way? Well, here is how you achieve it with 33 colors 🤯

![Grayscale](https://raw.githubusercontent.com/usalu/semio/⛳wip/semio/assets/lists/grayscale.png)

## 📄 Typography [↑](#-brand-)

> [!NOTE]
> Try to place notes either in the beginning or the end of a section ↕
> A starting note should contain something important but not crucial to give the brain the right context 🧠
> The starting sentence of a note needs no symbol because every note type starts with a symbol 🥇

- Be consistent with your language ♻
- When things are analogical use the same sentence structure for it 🔄
- One symbol after every sentance 💯
- One symbol at a time 🥇
- ➡️ No symbols ↔️ between blocks ⬅️
- A symbol is preferably an emoji or otherwise unicode ⚖️
- 📝 One symbol to summarize a title
- 💡 One symbol to summarize a title description and one to think about in the end 🤔
- `.` are forbidden ⛔
- All components in `semio` (`sketchpad`,`studio`, …) start with a small letter 🔡
- Did you know that `…` is just one character?

> [!TIP]
> In the end of a section you can give the curious reader a summarizing question to think about the consequences and a link to more resources 🤔

### 🔡 [Typesetting](semio/assets/README.md#fonts) [↑](#-typography-)

- Sans serif: [Anta](https://fonts.google.com/specimen/Anta) 🖨
- Serif: [Kelly Slab](https://fonts.google.com/specimen/Kelly+Slab) ✍
- Monospaced: [Shart Tech Mono](https://fonts.google.com/specimen/Share+Tech+Mono) 🖥
- Emoji: [Noto Emoji](https://fonts.google.com/noto/specimen/Noto+Emoji) ⚫

## 👀 Visual elements [↑](#-brand-)

- Sharp corners 📐
- Borders □
- Basic geometric shapes ⚪

# ⚖️ License

The files in this repository are licensed under the [GNU Affero General Public License](https://www.gnu.org/licenses/#AGPL) unless otherwise described. Most libraries, modules, extensions, objects or code herein are explicitly licensed. This is indicated in the root of the containing folder under a different license file, or in the configuration files of a bundle or in the respective file's header.

As a reference, different type of components have usually different licenses:

- software libraries and schemas: [LGPLv3 or later - GNU Lesser General Public License Version 3](https://www.gnu.org/licenses/lgpl-3.0.en.html)
- applications: [AGPLv3 or later - GNU Affero General Public License Version 3](https://www.gnu.org/licenses/agpl-3.0.en.html)
- examples: [MIT - The MIT License](https://mit-license.org)
- templates: [CC0 - No Rights Reserved](https://creativecommons.org/public-domain/cc0/)
- assets: [CC BY-ND 4.0 - Attribution-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nd/4.0/)

If you have any questions, please don't hesitate to get in touch with [us over email](mail@semio-tech.com) 📧

# 🔒 Security

If you have any security vulnerabilities or concerns, please contact [us over email](security@semio-tech.com) and don't open an issue, discussion or write into our public discord server 🥷

# ✨ [Contributors](https://github.com/usalu/semio/pulse/monthly) [↑](#-overview)

<table style="border-collapse: collapse; border: none;">
 <tbody>
 <tr style="border: none;">
 <td align="center" valign="top" width="145px" style="border: none;"><a href="https://github.com/usalu">
 <img src=".repo/👤/usalu/avatar-round-90x90.png" alt="Ueli Saluz" style="border-radius: 50%;"/>
 
 Ueli Saluz
 
 <a href="#-semiojs-" title="🟨semio/js">🟨</a>
 <a href="#-semionet-" title="🟪semio/net">🟪</a>
 <a href="#-python-" title="🐍Python">🐍</a>
 <a href="#-semiograsshopper-" title="🦗semio/grasshopper">🦗</a> 
 
 <a href="#-semiodesktop-" title="✏semio/desktop">✏</a>
 <a href="#-semioengine-" title="⚙️️semio/engine">⚙️️</a>
 <a href="#-semioassistant-" title="🤖semio/assistant">🤖</a>
 <a href="#%EF%B8%8F-semioplay-" title="🎛semio/play">🎛</a>
 
 <a href="#-semiodocs-" title="📚semio/docs">📚</a>
 <a href="#-semioassets-" title="🛍semio/assets">🛍</a>
 <a href="#-brand-" title="💯Brand">💯</a>
 
 <a href="#-semio.3dm-" title="🦏Rhino">🦏</a>
 <a href="#-semiowasp-" title="🐝Wasp">🐝</a>
 <a href="#-semiomonoceros-" title="🦌Monoceros">🦌</a>
 <a href="#-semioladybug-" title="🐞Ladybug">🐞</a>
 
 <a href="#-metabolism-" title="🫀Metabolism">🫀</a>
 <a href="#-hello-semio-" title="👋Hello semio">👋</a>
 <a href="#-starters-" title="🚀Starters">🚀</a>
 </td>
 <td align="center" valign="top" width="145px"><a href="https://github.com/kinansarak">
 <img src=".repo/👤/kinansarak/avatar-round-90x90.png" width="90px" alt="KinanSarak" style="border-radius: 50%;"/>
 
 KinanSarak</a>
 
 <a href="#-semiodocs-" title="📚semio/docs">📚</a>
 <a href="#-hello-semio-" title="👋 Hello semio">👋</a>
 <a href="#-semiograsshopper-" title="🦗semio/grasshopper">🦗</a> 
 </td>
 <td align="center" valign="top" width="145px"><a href="https://github.com/EinMysterium">
 <img src=".repo/👤/EinMysterium/avatar-round-90x90.png" width="90px" alt="EinMysterium" style="border-radius: 50%;"/>
 
 Christian Hödtke</a>
 
 <a href="#-semiograsshopper-" title="🦗semio/grasshopper">🦗</a>
 </td>
 <td align="center" valign="top" width="145px"><a href="https://github.com/AdrianoCelentano">
 <img src=".repo/👤/AdrianoCelentano/avatar-round-90x90.png" width="90px" alt="AdrianoCelentano" style="border-radius: 50%;"/>
 
 AdrianoCelentano</a>
 
 <a href="#-semiojs-" title="🟨semio/js">🟨</a>
 </td>
 <td align="center" valign="top" width="145px"><a href="https://github.com/ellumpine">
 <img src=".repo/👤/ellumpine/avatar-round-90x90.png" width="90px" alt="ellumpine" style="border-radius: 50%;"/>
 
 ellumpine</a>
 
 <a href="#-semiograsshopper-" title="🦗semio/grasshopper">🦗</a>
 <a href="#-semioladybug-" title="🐞ladybug">🐞</a>
 </td>
 <td align="center" valign="top" width="145px"><a href="https://github.com/kaatzjo">
 <img src=".repo/👤/kaatzjo/avatar-round-90x90.png" width="90px" alt="kaatzjo" style="border-radius: 50%;"/>
 
 kaatzjo</a>
 
 <a href="#-semioengine-" title="⚙️️semio/engine">⚙️️</a> 
 </td>
 <td align="center" valign="top" width="145px"><a href="https://github.com/pizzadizza">
 <img src=".repo/👤/pizzadizza/avatar-round-90x90.png" width="90px" alt="pizzadizza" style="border-radius: 50%;"/>
 
 pizzadizza</a>
 
 <a href="#-semioassistant-" title="🤖semio/assistant">🤖</a> 
 </td>
 </tr>
</table>

# 📊 [Stats](https://stats.docs.semio-tech.com)

We use [Goatcounter](https://www.goatcounter.com) for gaining insights about our [docs](#-semiodocs-) 📈

![Pixel](https://stats.docs.semio-tech.com/count?p=https://github.com/usalu/semio)

semio

semio Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

semio

semio Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README