KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

mnmlang

★ 40 Open GitHub ↗

What if a little pile of M&Ms on a table was a real program?

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MNM Lang

![Certified AI Slop](https://img.shields.io/badge/Certified%20AI%20Slop-ff69b4?style=flat)

> _Read my blog on this project: ["I made a programming language with M&Ms"](https://mufeedvh.com/posts/i-made-a-programming-language-with-mnms/)_

MNM Lang is a toy programming language where source code is a grid of candy colors.

You write programs as whitespace-separated runs of six letters:

- `B` blue
- `G` green
- `R` red
- `Y` yellow
- `O` orange
- `N` brown

Those runs compile into a PNG made out of M&M-style sprites. The PNG can be
decompiled back into source exactly, and a controlled photo decoder can recover
programs from mildly skewed overhead images on a plain background.

This repository ships:

- a parser and canonical formatter for `.mnm` source
- a stack-machine interpreter
- a source-to-PNG compiler
- a PNG/photo-to-source decompiler
- a local FastAPI playground
- six generated candy sprites plus normalization scripts
- example programs for `hello_world`, `echo_name`, `factorial`, and `fizzbuzz`
- a test suite covering parsing, runtime behavior, rendering, vision decoding,
  assets, and the HTTP API

## Why It Exists

This project started from a deliberately silly premise:

> what if a pile of M&Ms on a table was a real program?

The interesting part is that the constraint is actually sharp. You only get six
colors, and images are hostile to precise symbolic data. That forces the design
to become visual-first:

- instructions must be recognizable by color family
- operands must be encoded by candy count rather than printed text
- strings and initial variables live outside the image in a sidecar JSON file
- the renderer has to produce exact round-trippable sheets
- the photo decoder has to be conservative instead of pretending it can solve
  arbitrary “messy real world candy OCR”

## Quickstart

Requirements:

- Python 3.13+
- [`uv`](https://github.com/astral-sh/uv)

You can either let `uv run` resolve everything on demand, or create a local
virtual environment up front:

```bash
uv sync --extra dev
```

After that, the commands below work as written. If you prefer not to sync first,
`uv run ...` will still create an environment automatically.

Run an example:

```bash
uv run mnm run examples/hello_world/hello_world.mnm
uv run mnm run examples/factorial/factorial.mnm
```

Compile source into a candy-sheet PNG:

```bash
uv run mnm compile examples/hello_world/hello_world.mnm
```

Decompile a rendered PNG back into source:

```bash
uv run mnm decompile examples/hello_world/preview.png
```

Start the local playground:

```bash
uv run mnm serve
```

Run the full test suite:

```bash
uv run --extra dev pytest
```

## The Source Format

Each non-comment row is exactly one instruction.

- The first token is the opcode cluster.
- Later tokens are operands.
- Each token must be one repeated color letter.
- Operand values are `len(token) - 1`.

Example:

```text
OO Y
OOOOOO
BBBBBB
```

That means:

- `OO` = `PRINT_STR`
- `Y` = string slot `0`
- `OOOOOO` = `NEWLINE`
- `BBBBBB` = `HALT`

Comments start with `#`, and blank lines are ignored.

## Operand Encoding

Operand meaning depends on color:

| Color | Meaning | Example |
| --- | --- | --- |
| `R` | integer literal | `RRR` means `2` |
| `G` | variable slot | `GG` means variable `1` |
| `Y` | string slot | `YYY` means string `2` |
| `B` | label id | `BBBB` means label `3` |
| `O` | input queue id | `OO` means queue `1` |
| `N` | invalid as operand in v1 | rejected |

## Opcode Table

### Blue: control flow

| Token | Mnemonic | Meaning |
| --- | --- | --- |
| `B` | `JMP` | unconditional jump |
| `BB` | `JZ` | jump if popped value is zero |
| `BBB` | `JNZ` | jump if popped value is non-zero |
| `BBBB` | `CALL` | call subroutine |
| `BBBBB` | `RET` | return from subroutine |
| `BBBBBB` | `HALT` | stop execution |

### Green: stack and variables

| Token | Mnemonic | Meaning |
| --- | --- | --- |
| `G` | `PUSH` | push integer literal |
| `GG` | `LOAD` | push variable value |
| `GGG` | `STORE` | pop into variable |
| `GGGG` | `DUP` | duplicate top of stack |
| `GGGGG` | `POP` | discard top of stack |
| `GGGGGG` | `INC` | increment variable |
| `GGGGGGG` | `DEC` | decrement variable |

### Yellow: arithmetic and comparisons

| Token | Mnemonic | Meaning |
| --- | --- | --- |
| `Y` | `ADD` | `a + b` |
| `YY` | `SUB` | `a - b` |
| `YYY` | `MUL` | `a * b` |
| `YYYY` | `DIV` | integer floor division |
| `YYYYY` | `MOD` | modulo |
| `YYYYYY` | `EQ` | equality test |
| `YYYYYYY` | `LT` | less-than test |
| `YYYYYYYY` | `GT` | greater-than test |

### Orange: input and output

| Token | Mnemonic | Meaning |
| --- | --- | --- |
| `O` | `PRINT` | pop and print value |
| `OO` | `PRINT_STR` | print sidecar string directly |
| `OOO` | `READ_INT` | read from integer queue |
| `OOOO` | `READ_STR` | read from string queue |
| `OOOOO` | `EMIT_CHAR` | pop integer and print `chr(value)` |
| `OOOOOO` | `NEWLINE` | print newline |

### Brown: labels and strings

| Token | Mnemonic | Meaning |
| --- | --- | --- |
| `N` | `LABEL` | declare label |
| `NN` | `PUSH_STR` | push sidecar string |
| `NNN` | `CONCAT` | `str(a) + str(b)` |
| `NNNN` | `LEN` | length of top value |
| `NNNNN` | `TO_INT` | convert to integer |
| `NNNNNN` | `TO_STR` | convert to string |

### Red: stack shuffling and logic

| Token | Mnemonic | Meaning |
| --- | --- | --- |
| `R` | `SWAP` | swap top two values |
| `RR` | `ROT` | rotate top three values left |
| `RRR` | `AND` | logical and |
| `RRRR` | `OR` | logical or |
| `RRRRR` | `NOT` | logical not |

## Sidecar JSON

Strings and initial state live in a sibling `.mnm.json` file:

```json
{
  "strings": ["Hello, world!"],
  "variables": [1, 15, 15, 3, 5],
  "inputs": {
    "int": [[5]],
    "str": [["Ada"]]
  }
}
```

Why a sidecar?

- putting arbitrary strings into candy photos is miserable
- OCR is the opposite of fun here
- sidecar data keeps the visual language legible
- the same program image can be run with different inputs without moving candy

## Examples

### Hello world

Source:

```text
OO Y
OOOOOO
BBBBBB
```

Sidecar:

```json
{
  "strings": ["Hello, world!"],
  "variables": [],
  "inputs": { "int": [], "str": [] }
}
```

Output:

```text
Hello, world!
```

### Factorial

Reads `n` from integer queue `0`, loops until `n <= 1`, and prints `n!`.

```text
OOO O
GGG G
G RR
GGG GG
N B
GG G
G RR
YYYYYYYY
BB BB
GG GG
GG G
YYY
GGG GG
GGGGGGG G
B B
N BB
GG GG
O
OOOOOO
BBBBBB
```

### FizzBuzz

The `fizzbuzz` example uses:

- labels
- variables
- modulo
- conditional branches
- direct string-slot output

See [`examples/fizzbuzz`](examples/fizzbuzz) for the full program.

## CLI Reference

### `mnm compile`

Render `.mnm` source into a PNG:

```bash
uv run mnm compile path/to/program.mnm
uv run mnm compile path/to/program.mnm --output out/program.png
```

### `mnm decompile`

Recover canonical source from a PNG or controlled photo:

```bash
uv run mnm decompile path/to/program.png
uv run mnm decompile path/to/photo.png --mode photo
```

Decode modes:

- `auto`: try exact rendered-image decoding first, then the photo pipeline
- `rendered`: require compiler-grid geometry
- `photo`: force the controlled photo decoder

### `mnm run`

Execute source or image input:

```bash
uv run mnm run path/to/program.mnm
uv run mnm run path/to/program.png --mode auto
uv run mnm run path/to/program.mnm --show-state
uv run mnm run path/to/program.mnm --show-ast --show-trace
```

If `program.mnm.json` exists next to the input file, it is loaded automatically.
`--show-ast` and `--show-trace` print tree-formatted parser/runtime views for
visualizing the program structure and the path the interpreter actually took.

### `mnm serve`

Start the local browser playground:

```bash
uv run mnm serve --host 127.0.0.1 --port 8000
```

### `mnm examples`

List shipped example programs:

```bash
uv run mnm examples
uv run mnm examples --json
```

## Image Pipeline

There are two image paths in this repo.

### 1. Exact compiler images

This is the easy path:

- source is rendered on a fixed transparent grid
- one source character maps to one cell
- decompilation reads the grid geometry exactly
- round-tripping is lossless

### 2. Controlled photos

This is the harder path:

- image processing estimates the background color
- non-background blobs become candidate candies
- blobs are classified into one of six canonical colors
- centroids are clustered into rows
- horizontal gaps infer spaces
- the reconstructed text is re-parsed for validation

This is intentionally scoped. v1 supports:

- overhead photos
- separated candies
- plain contrasting background
- mild blur
- small rotation or perspective skew

It does **not** try to solve:

- cluttered tables
- overlapping candies
- arbitrary lighting
- giant perspective distortion
- fingers, bowls, packaging, or mixed snacks

## Generated Sprites

The six canonical sprite prompts are checked in at
[`assets/sprites/prompts.jsonl`](assets/sprites/prompts.jsonl).

To regenerate raw sprite renders with the local `imagegen` skill install:

```bash
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
uv run --with openai --with pillow python "$CODEX_HOME/skills/imagegen/scripts/image_gen.py" \
  generate-batch \
  --input assets/sprites/prompts.jsonl \
  --out-dir output/imagegen/raw \
  --concurrency 3 \
  --force
```

Normalize those raw renders into the committed canonical sprite pack:

```bash
uv run --with scikit-image python scripts/normalize_sprites.py
```

Regenerate example preview images:

```bash
uv run python scripts/render_examples.py
```

## Web Playground

The browser playground is local-only and intentionally simple:

- load a shipped example
- edit source and sidecar JSON
- render a live candy-sheet preview
- run the interpreter
- inspect the AST tree
- inspect the execution trace tree
- upload an image and decode it back into source

The frontend is plain HTML, CSS, and JS. No build step, no bundler, no extra
frontend framework.

## Repository Layout

```text
assets/sprites/           canonical candy sprites and prompt bundle
examples/                 example programs, sidecars, expected output, previews
scripts/                  sprite normalization and preview regeneration scripts
src/mnm_lang/             parser, runtime, renderer, vision decoder, CLI, app
tests/                    parser/runtime/render/vision/API/asset tests
```

## Design Tradeoffs

### Why count-based operands?

Because “three blue candies means something” is the whole point.

Token length is:

- visual
- human-placeable
- easy to parse
- easy to decompile back from an image

### Why not encode strings in candy too?

Because that would either:

- explode the visual complexity, or
- smuggle a second encoding system into the image and defeat the joke

The sidecar keeps the fun part fun.

### Why not train a neural model?

I considered it. For v1, a deterministic blob detector was the right tool:

- far easier to debug
- reproducible in tests
- good enough for controlled photos
- no model weights to ship

If the next version targets chaotic phone photos, a learned classifier becomes
more compelling.

## Limitations

- Photo decoding is conservative by design.
- Variables must exist in the sidecar before `LOAD`, `STORE`, `INC`, or `DEC`.
- Runtime input queues are finite; exhausting one is a hard error.
- Arithmetic instructions require integers.
- The renderer and exact decompiler target the canonical sprite pack only.

## Testing

The test suite covers:

- parser validation
- sidecar validation
- runtime semantics
- example golden outputs
- source -> PNG -> source round-trips
- synthetic photo decoding with blur, rotation, and perspective skew
- API behavior and a playground smoke flow
- sprite asset dimensions and transparency

Run it with:

```bash
uv run --extra dev pytest
```

## License

This repository is intended as a playful programming-language experiment. The
generated candy sprites are original project assets produced for this repo.

mnmlang

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README