Skip to content
mashin

Introduction to mashin

Build an email triage system from scratch. Start with 6 lines. End with a self-improving, production-deployed machine.

The Scenario

You get 150 emails a day. You will build a machine that classifies them, routes urgent ones to your team via Microsoft Teams, creates tasks in Planner, learns from your corrections, and monitors itself.

Each lesson adds one capability. No lesson assumes knowledge from outside this course.

Prerequisites

None. If you can write an email, you can build a machine.

What is mashin?

mashin is a governed intelligence substrate: a deterministic foundation for building, running, and governing intelligent software. At its core is a language (also called mashin) that compiles to BEAM bytecode. You write .mashin files that define machines: portable cognitive computers with typed inputs, outputs, and governed execution.

If You Have Used ChatGPT or Claude

You already understand more than you think. Here is how concepts you know map to mashin:

What you knowmashin equivalent
Giving AI a persona (“You are a helpful assistant…”)with role (sets the AI’s role)
Writing a prompt (“Classify this text…”)with task (the instruction)
Getting structured JSON outputreturns (declares the shape of the response)
Using plugins or function callingTools in ask steps (governed actions the AI can take)
A Custom GPT or Claude ProjectA machine (a self-contained, reusable unit of work)
A multi-step workflow in Zapier or MakeA flow of steps (each step does one thing, in order)

This course teaches you to build and understand machines. You do not need to write code from scratch. Koda (mashin’s intelligent development environment) can generate machines from natural language descriptions. This course teaches you to read, understand, and customize what Koda builds.

Why Does This Exist?

AI workflows written in raw Python or JavaScript suffer from three problems:

  1. No governance: API keys hardcoded, no audit trail, anyone can run anything
  2. No structure: scattered scripts, unclear data flow, impossible to test in isolation
  3. No safety: code can do anything, including things you did not intend

mashin solves this with one principle: code computes, machines effect. Pure computation cannot access the outside world. All side effects (HTTP calls, file operations, database access) go through governed effect machines that are tracked, permission-controlled, and auditable.

Key Terms

TermDefinition
MachineA portable cognitive computer defined in a .mashin file
StepA single operation within a machine. Types: compute (computation), ask...from: (invoke another machine), ask...using: (AI inference), remember/recall (memory), decide (conditional routing)
FlowA named sequence of steps. The main flow runs first when the machine is invoked
Effect machineA machine whose job is to perform a governed side effect (like making a web request or reading a file)
StdlibThe standard library (@mashin/actions/*): pre-built effect machines that ship with mashin
GovernedEvery step is tracked, permission-controlled, and auditable

Reading mashin Syntax

mashin uses MashinTalk, an indentation-based keyword-hierarchy syntax. Here is a quick guide:

machine classify_email       A machine definition
  accepts                    Declares what data the machine accepts
    subject as text          A typed input field
  responds with              Declares what data the machine returns
    priority as text         A typed output field
  implements                 The behavior section
    ask classify, using: "anthropic:claude-haiku-4"   An AI reasoning step
      with task "Classify this email"                 The instruction
      returns                                         What the AI returns
        priority as text
    compute format           A pure computation step (no I/O)
      {summary: classify.priority}
    decide route             A conditional routing step
      if classify.priority == "urgent"
        {action: "notify"}

Do not worry about memorizing this. It will become natural as you work through the lessons.

A Quick Example

Here is a complete machine that classifies an email:

machine classify_email


implements
  ask classify, using: "anthropic:claude-haiku-4"
    with task "Is this email urgent, routine, or ignorable?\n\nSubject: ${input.subject}\nFrom: ${input.sender}"
    returns
      priority as text
      reason as text

That is the whole thing. Six lines. This course teaches you to build progressively more capable machines like this.

What You Will Learn

By the end of this course, you will be able to:

  • Read and understand any .mashin file
  • Write machines with typed inputs, outputs, and structured AI responses
  • Route decisions based on classification and confidence
  • Connect machines to real systems (Teams, Planner, APIs)
  • Compose machines from other machines
  • Deploy, schedule, and monitor machines in production
  • Add goals, tests, and memory
  • Use interpretation modes to analyze machines
  • Understand governed metaprogramming

How to Use This Course

Each lesson follows a pattern:

  1. Problem: What you are solving and why it matters
  2. Build it: The machine code, explained line by line
  3. Run it: What you see when you execute it
  4. What changed: How this builds on the previous lesson

Estimated time: 3-4 hours total (15-25 minutes per lesson)

Lessons

#LessonWhat You Add
01Your First Machine6-line email classifier
02Inputs, Outputs, and StructureContract with type constraints
03Decisions and RoutingRoute by priority and confidence
04Taking ActionSend Teams messages, create Planner tasks
05CompositionMulti-flow organization, machine-to-machine calls
06Going LiveDeploy as API, schedule, monitor
07Goals and TestsSuccess contract, automated test suite
08MemoryLearn from patterns and human corrections
09Interpretation ModesExplain, cost, verify without running
10MetaprogrammingSelf-inspection and self-improvement

Reference Material

These pages are referenced throughout the course: