CLAUDE.md

Language: Moxie

This project uses Moxie — a compiled systems language for domain-isolated programs. Moxie descends from TinyGo but is its own language with .mx source files, moxie.mod modules, and a restricted execution model.

Read [../moxie/REFERENCE.md](../moxie/REFERENCE.md) before writing any code.

Hard Rules

These are compile errors. Violating them wastes a build cycle.

Type System

• string and []byte are the same type. Identical 3-word layout (ptr, len, cap). Mutually assignable. Use string in signatures for readability.
• int and uint are always 32-bit. len() and cap() return int32.
• range over text yields bytes, not runes.

Forbidden Constructs

Construct	Compile Error	Use Instead
go f()	No goroutines	Channels + select for dispatch, spawn for isolation
make(T, ...)	Removed	Literal syntax: []T{:n}, chan T{}, map[K]V{}
new(T)	Removed	&T{} or var x T; p := &x
"a" + "b"	No + on text	"a" \| "b" (pipe operator)
fallthrough	Removed	case A, B: comma-separated
complex64/128	Removed	Not supported
uintptr	Removed	Explicit pointers. Allowed with import "unsafe"
import "strings"	Removed	import "bytes" (they're the same type)

Literal Syntax

Moxie	Description
[]T{:n}	Slice with length n
[]T{:n:c}	Slice with length n, capacity c
chan T{}	Unbuffered channel
chan T{n}	Buffered channel with capacity n
map[K]V{}	Empty map

make() is a compile error in user code. Use literal syntax only.

Build

make build
# or directly:
MOXIEROOT=../moxie ../moxie/moxie build -o gitweb .

Architecture

gitweb is a single-file Moxie application (main.mx) that serves a git hosting frontend. It implements HTTP handling directly (raw TCP + manual HTTP parsing) because net/http is broken in Moxie's runtime. Deployed via Docker to git.smesh.lol.

Key details:

• Single .mx source file
• Uses unsafe and syscall for raw clone/execve (git-http-backend CGI)
• Markdown rendering built-in (GFM tables, code fences, relative links)
• string=[]byte aliasing means bytes.Buffer.String() returns an alias — copy if reusing the buffer

Known Moxie Bugs (work around, don't fix here)

• net/http broken — bypass entirely, use raw TCP + manual HTTP parsing
• SetReadDeadline causes instant timeout — never use net.Conn deadlines
• Sprintf can corrupt earlier results (string=[]byte means shared backing) — always copy

Fix upstream in ../moxie first, then rebuild gitweb.

Dependencies

ALLOWED:

• Moxie standard library
• Packages already in go.mod

FORBIDDEN without approval:

• Any new dependency not already in go.mod
• Any npm/node ecosystem tool

Change Discipline

• Small commits, one feature at a time
• Verify compile AND run before moving on
• Re-read modified files after changes to catch drift
• When fixing a bug, understand the root cause before writing code
• Do not refactor adjacent code while fixing a bug
• Do not create test files unless explicitly asked
• Do not introduce abstractions "for future flexibility"
• Do not modify build configuration without approval

Code Style

• Direct, minimal, no abstraction for abstraction's sake
• If a function does one thing and is called once, inline it
• Concise variable names
• Comments only where the why isn't obvious from the what
• No boilerplate, scaffolding, or template code "you might need later"
• Prefer explicit over clever
• Prefer flat over nested

What NOT To Do

• Never add dependencies without explicit approval
• Never refactor working code that wasn't asked about
• Never introduce abstractions for future flexibility
• Never use frameworks when stdlib suffices
• Never explain code you're about to write — just write it
• Never summarize changes after making them unless asked
• Never create files that weren't requested
• Never modify build/dependency manifests without approval
• Never assume the tech stack — read the project first
• Never optimize before it works
• Never use go keyword (it's a compile error)
• Never use + for text concatenation (use |)
• Never use make() (use literal syntax)
• Never use new(T) (use &T{})