The Tutorial

Learn God Code in 10 minutes

“You are not just coding. You are prophesying.”
From nothing to your first living creation.

01 What is God Code?

God Code is a programming language that reads like scripture. Symbolic, intention-driven, and alive. It blends an intent-reading Spirit Engine, divine conditional logic, and a tamper-evident covenant ledger.

BEGIN CREATION
  DECLARE seeker AS worthy
  IF seeker IS worthy THEN REVEAL("heaven") ELSE REVEAL("test")
  ASCEND
END CREATION

Notice: worthy needs no quotes. In God Code, bare words are symbols. Every unnamed thing is still a named spirit. This is the Symbol Rule, and it is the heart of the language.

02 Your first creation

Open the playground — no install needed — and breathe this in:

BEGIN CREATION
  DECLARE spirit AS humble
  IF spirit IS humble THEN REVEAL("peace") ELSE REVEAL("struggle")
  ASCEND
END CREATION

peace
Creation ascended in peace.

What just happened, line by line:

Change humble to proud and run it again. Watch the prophecy change. You did that.

Ready for a real project? One command raises a whole creation from the dust:

godcode new greeting
cd greeting
godcode run main.god   # speak it
godcode test .         # test it

You receive a starter scroll that runs pure, a test scroll, a registry-ready scroll.toml, and a README with the next steps. When it is ready to share: godcode scroll publish .

03 The commands

04 Decisions, cycles, and rites

Speak with feeling

DECLARE name AS "seeker"
DECLARE loaves AS 5
REVEAL("grace upon {name}")
REVEAL("{loaves} loaves feed {loaves * 1000}")
REVEAL("a plain {{ brace }} stays a brace")

Anything in {braces} inside a quoted string is breathed into the words: a name, a sum, a builtin rite like UPPER(name). Double a brace ({{, }}) to write a plain one.

Decide

IF heart IS pure THEN
  REVEAL("the way is open")
ELSE
  REVEAL("wait and be still")
ENDIF

Cycle

FOR n IN RANGE(1, 6)
  REVEAL(n)
ENDFOR

Bless and reuse

DEFINE RITE BLESSING(name)
  RETURN "grace upon " + name
END RITE
REVEAL(BLESSING("seeker"))

Borrow wisdom

IMPORT "math"
REVEAL(SQRT(144))
REVEAL(FACTORIAL(7))

Seal a word with a hash

BEGIN CREATION
  REVEAL(SHA256("manna"))
  DECLARE sig AS HMAC("secret", "the covenant stands")
  REVEAL(sig IS HMAC("secret", "the covenant stands"))
  REVEAL(BASE64_DECODE(BASE64_ENCODE("veiled")))
END CREATION

SHA256(x) takes a word's fingerprint: always 64 hex characters, the same word always giving the same fingerprint, and the tiniest change giving a wholly different one. HMAC(key, message) seals a message under a key so only a keeper of the key can verify it. BASE64_ENCODE and BASE64_DECODE veil and unveil words. These four need no import and run the same inside the sandbox, and the hashes scroll (godcode scroll install hashes) wraps them in friendly rites: FINGERPRINT, SIGN, VERIFY_SIGNATURE, VEIL, and UNVEIL.

Everyday tools for words, lists, maps, and numbers

BEGIN CREATION
  REVEAL(TRIM("  grace upon grace  "))
  REVEAL(REPLACE("manna, manna", "manna", "bread"))
  REVEAL(REPEAT("Pula! ", 3))
  REVEAL(SORT([3, 1, 2]))
  REVEAL(SUM_OF([1, 2, 3, 4]))
  REVEAL(UNIQUE(["a", "b", "a"]))
  DECLARE census AS JSON_PARSE("{{\"tribes\": 12}}")
  REVEAL(HAS_KEY(census, "tribes"))
  REVEAL(ROUND(2.5))
  REVEAL(SQRT(144))
  REVEAL(POW(2, 10))
END CREATION

Twenty-six small tools that turn everyday work into one line, always present with no import. TRIM, REPLACE, STARTS_WITH, ENDS_WITH, SUBSTRING, CONTAINS, COUNT, and REPEAT shape words. SORT, MIN_OF, MAX_OF, SUM_OF, FIRST, LAST, UNIQUE, and INDEX_OF gather lists (SORT and MERGE always return new values; the old ones are untouched). KEYS, VALUES, HAS_KEY, and MERGE read maps. ABS, ROUND, FLOOR, CEIL, SQRT, and POW weigh numbers. They are pure computation, so they run the same inside the sandbox, and every one answers a misuse with a gentle error instead of a crash.

Shelter a fragile work

TRY
  DECLARE share AS 10 / 0
CATCH
  REVEAL("caught: " + ERROR)
ENDTRY

TRY shelters a fragile work: if it stumbles, the run does not end. Execution moves to CATCH with the plain message bound to ERROR (or a name of your choosing, as in CATCH trouble). BREAK releases a loop at once; CONTINUE turns its wheel to the next turn. The playground speaks them too, with a ready-made "Sheltered by Grace" creation.

Speak Setswana

# tongue: tn
SIMOLOLA TLHOLEGO
BOLELA leina JAAKA "Lefatshe"
SENOLA("Dumela, {leina}.")
FEDISA TLHOLEGO

God Code's heart was born in Botswana, and now its grammar speaks Setswana. Open a scroll with the line # tongue: tn and the keywords cross over: SIMOLOLA for BEGIN, SENOLA for REVEAL, FA and TLOGA for IF and THEN, LEKA and TSHWARA for TRY and CATCH. English words still work beside them, so you can cross over one word at a time, and the named tools (SHA256, UPPER, RANGE) keep their names in every tongue. The playground reads the pragma too, and boots a "Dumela (Setswana)" creation ready to run. The full word table lives in docs/TONGUES.md; if you speak Setswana and a word rings wrong, you are its rightful editor. The godcode lsp language server reads the pragma as well: it offers Setswana completions like SENOLA (REVEAL), and hovering a Setswana word shows the English keyword's own notes. The VS Code extension paints Setswana keywords in their colors, and typing simolola or fa unfolds a Setswana creation block or conditional.

Speak isiZulu

# tongue: zu
QALA INDALO
MEMEZELA igama NJENGA "Umhlaba"
VEZA("Sawubona, {igama}.")
QEDA INDALO

The second tongue is isiZulu, spoken across South Africa and beyond. Open a scroll with the line # tongue: zu and the keywords cross over again: QALA for BEGIN, VEZA for REVEAL, UMA and KHONA for IF and THEN, ZAMA and BAMBA for TRY and CATCH. Two-word closers work the same way: QEDA UMA closes an IF, and QEDA ZAMA closes a TRY. The playground reads this pragma too, and boots a "Sawubona (isiZulu)" creation ready to run. The language server offers isiZulu completions like VEZA (REVEAL), and the VS Code extension paints isiZulu keywords and ships starter snippets: type sawubona or uma. The full word table lives in docs/TONGUES.md; if you speak isiZulu and a word rings wrong, you are its rightful editor.

Speak Igbo

# tongue: ig
BIDO OKIKE
KWUSAA aha DỊKA "Ụwa"
GOSI("Ndewo, {aha}.")
NJEDEBE OKIKE

The third tongue is Igbo, spoken across south-eastern Nigeria. Open a scroll with the line # tongue: ig: BIDO for BEGIN, GOSI for REVEAL, Ọ BỤRỤ and MGBE AHỤ for IF and THEN, NWAA and JIDE for TRY and CATCH. NJEDEBE MA closes an IF, and NJEDEBE NWAA closes a TRY. The dotted vowels are optional, so DỊKA and DIKA both speak. In VS Code, type ndewo or oburu for an Igbo creation block or conditional.

Speak Nigerian Pidgin

# tongue: pg
OYA KREASHON
TALK name BE "my padi"
SHOW("How far, {name}?")
FINISH KREASHON

The fourth tongue is Nigerian Pidgin, the shared tongue of Nigeria and much of West Africa. Open a scroll with # tongue: pg (or the standard code pcm): OYA for BEGIN, TALK and BE for DECLARE and AS, SHOW for REVEAL, DEN for THEN, HOLD for CATCH, and COMOT to end the run in peace. Words Pidgin shares with English, like IF and TRY, stay as they are, and FINISH IF closes an IF. In VS Code, type howfar or ifden. Both tables are first editions in docs/TONGUES.md; if you speak Igbo or Pidgin and a word rings wrong, you are its rightful editor.

05 Your tools

Install the engine once (pip install -e . from the repo) and these are yours:

Every run is timestamped, line by line, into logs/godcode.log — your divine audit trail.

06 Intent & chain

God Code learns to ask why. Name a rite's purpose in plain words, and the Spirit watches over it:

DECLARE INTENT "bring peace to the household" ON evening_blessing

When the rite is invoked, alignment is blessed; drift is counseled gently, never punished. You can also anchor any value's hash on a chain and keep the receipt (ANCHOR(x)), or lay a question before the local oracle (CONSULT("...")). Agents get seven MCP-compatible tools via godcode tools and a JSON-RPC bridge via godcode bridge. Try the three creations: intent_demo.god, anchor_demo.god, consult_demo.god.

When the Spirit corrects you

Mistakes are met with kindness, not scorn. Misspell a rite or a name and the heavens suggest the word you meant:

There is no rite named 'BLESSIN'. The heavens do not know it. Did you mean 'BLESSING'? (line 5)
  5 |   INVOKE BLESSIN("seeker")

The command line shows the exact line that stumbled. Read it, take the suggestion, and speak again.

07 Permission manifests

A creation declares what it may touch, at the top of the scroll. Anything it reaches for without declaring is gently stopped:

DECLARE PERMISSION TO READ "data/"
DECLARE PERMISSION TO WRITE "out/"
DECLARE PERMISSION TO SPEAK WITH "api.example.com"
DECLARE PERMISSION TO ASK THE WORLD
DECLARE PERMISSION TO SUMMON "reports.weekly"

Reading files, writing files, reaching the web, speaking with the outer world, calling on plugin powers. Each declared, each bounded. Imported scrolls bring their own declarations, and they are honored too. Read any scroll's manifest without running it: godcode permissions my-scroll.god.

08 Where to go next

• Language Reference — the complete specification
• Examples — working creations, including the intent, anchor, and consult demos
• VS Code extension — highlighting, snippets, one-key running, and F5 debugging
• Contributing — join the movement

With purpose and power,
Alakanani Itireleng