forgo.cloud
Sign in
Repo workspace

forkjoin-ai/gnosis

Getting Started With Gnosis

docs/GETTING_STARTED.md
forkjoin-ai/gnosis
Repo overview Open in workbench

Getting Started With Gnosis

Parent README: ../README.md

GG developer spine: GG_DEVELOPER_GUIDE.md, GG_LANGUAGE_REFERENCE.md, GG_CLI_REFERENCE.md, GG_MODULES_AND_EXTENSIONS.md, GG_SURFACE_MAP.md.

This guide is for a capable developer who wants to understand what Gnosis helps with before learning the formal vocabulary.

New here and want the wild version first? Read the Monster · FOIL · protocol69 ELI5 — a friendly tour of how a program is compiled to a graph, cached by its shape, and teleported with a one-number handshake (it even flies across a room over radio).

Gnosis helps you turn code and workflows into executable graphs. That graph view lets you see which work is linear, which work can split apart, which branch wins or fails, and how the runtime folds results back into one answer. The deeper math and proof surfaces stay available when you need them, but you do not need to start there.

What You Need

  • Node 22+
  • pnpm
  • Rust/Cargo for the native Monster and polyglot paths
  • A checkout of this monorepo from the repo root

Most workspace commands should go through the repo-owned surfaces. For this package, that usually means:

pnpm --dir open-source/gnosis run <script>

First Command

Run a tiny TypeScript fixture through the native Gnosis execution path:

GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:echo

Then run a small compute fixture:

GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:fib20

These commands are intentionally small. They are the fastest way to prove that your local checkout can invoke Gnosis, pass JSON input into a checked-in program, and execute the extracted runtime shape. The GNODE_FORCE_TSX=1 prefix keeps the first run on the live TypeScript bridge even when the optional prewarmed bundle is stale for the current workspace.

First Mental Model

Start with ordinary engineering terms:

  • A workflow graph is the shape of the work your program does.
  • A node is one unit of work.
  • An edge says what can run after, beside, or instead of another node.
  • Fork splits work into branches.
  • Race lets branches compete or chooses the first useful result.
  • Fold combines branch results back into one value.
  • A runtime executes the graph and enforces the rules.
  • A proof or provenance link records why a contract or optimization is allowed to make a stronger claim.

That vocabulary is enough to start reading the repo. The formal language comes later when you need exact contracts.

First Example Path

If you want to learn by reading files, use this order:

  1. ../example.gg for a small graph-language example.
  2. ../betti.gg for a compact topology used throughout the docs.
  3. ../examples/README.md for the wider example map.
  4. ../gnode/README.md if you prefer TypeScript-first workflows.
  5. ../polyglot/README.md when you want to extract existing language/framework code.

Which Tool Should I Reach For?

  • Use gnode when you have TypeScript and want Gnosis to compile a supported orchestration subset into a graph.
  • Use .gg files when you want to author or inspect the graph directly.
  • Use monster when you want the native runtime path that executes extracted topologies.
  • Use polyglot when you are asking, "Can Gnosis understand this other language or framework shape?"
  • Use the formal ledger, Lean, or TLA+ when a downstream contract needs proof provenance instead of only test evidence.

What The Richer Material Is For

The top-level README keeps performance notes, compiler-family details, formal ledgers, specialized transport experiments, and theorem-backed reducer contracts. That material is not decoration. It records the technical depth that supports the project.

Read it after the basics above when you need to answer questions like:

  • Which runtime should host this workload?
  • Is this benchmark local, portable, or experimental?
  • Which theorem or ledger row backs this contract?
  • Which package boundary should a downstream app import from?
  • Is this surface ready for production use, or is it a research lane?

Where To Go Next