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 an intent-driven computing platform. Programs produce intents, not effects. The runtime mediates every intent before execution. At its core is a purpose-built language (also called mashin) designed for governed intelligence. You write .mashin files that define machines: portable cognitive computers with typed inputs, outputs, and governed execution. Governance is a structural consequence of operating at the intent layer, not something bolted on after the fact.

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 know	mashin 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 output	returns (declares the shape of the response)
Using plugins or function calling	Tools in ask steps (governed actions the AI can take)
A Custom GPT or Claude Project	A machine (a self-contained, reusable unit of work)
A multi-step workflow in Zapier or Make	A 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 act. Pure computation cannot access the outside world. All side effects (HTTP calls, file operations, database access) go through governed action machines that are tracked, permission-controlled, and auditable.

Key Terms

Term	Definition
Machine	A portable cognitive computer defined in a .mashin file
Step	A single operation within a machine. Types: compute (computation), ask...from: (invoke another machine), ask...using: (AI inference), remember/recall (memory), decide (conditional routing)
Flow	A named sequence of steps. The main flow runs first when the machine is invoked
Action machine	A machine whose job is to perform a governed side effect (like making a web request or reading a file)
Stdlib	The standard library (@mashin/actions/*): pre-built action machines that ship with mashin
Governed	Every 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
  behaves                 // 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
      when classify.priority == "urgent"
        {action: "notify"}
      otherwise
        {action: "file"}

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

accepts
  subject as text, is required
  sender as text

responds with
  priority as text
  reason as text

behaves
  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

verifies
  test "classifies an email"
    assuming classify {priority: "routine", reason: "newsletter"}
    given {subject: "Weekly digest", sender: "[email protected]"}
    expect {priority: "routine", reason: "newsletter"}

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

#	Lesson	What You Add
01	Your First Machine	6-line email classifier
02	Inputs, Outputs, and Structure	Contract with type constraints
03	Decisions and Routing	Route by priority and confidence
04	Taking Action	Send Teams messages, create Planner tasks
05	Composition	Multi-flow organization, machine-to-machine calls
06	Going Live	Deploy as API, schedule, monitor
07	Goals and Tests	Success contract, automated test suite
08	Memory	Learn from patterns and human corrections
09	Interpretation Modes	Explain, cost, verify without running
10	Metaprogramming	Self-inspection and self-improvement

Reference Material

These pages are referenced throughout the course:

• Key Concepts - machines, steps, governance, computers
• Machine Anatomy - the five layers of a machine
• Actions - “code computes, machines act”
• Platform Overview - how all the components fit together