Execution flow

jaiph graph shows how a workflow runs before anyone runs it. It draws the order of the steps, where the workflow branches, which calls run in parallel, what happens when a step fails, and which def handles each message. The command reads a .jh file and prints a Mermaid flowchart, which GitHub, many Markdown editors, and the Mermaid live editor can draw. It doesn’t call any agent or script, so it is safe to run on any file that compiles.

jaiph graph examples/say_hello.jh > say_hello.mmd

The chart starts at main unless --def <name> picks another def. The flags are listed in CLI reference, and the examples at the end of this page show the chart for each program in the examples folder.

How to read the chart

Each def is a grey box with the def’s name at the top. The steps inside the box run from top to bottom, from start to end. When a def calls another def, an arrow goes from the call into the box of the called def, and the arrow that leaves that box’s end goes back to the step after the call. Each def is drawn once, even when several steps call it. The def the chart starts at is on the left, and the defs it calls are to its right. Two defs that the starting def runs in parallel with async are drawn on either side of it.

A def from an imported file keeps the name it was imported under, e.g. git.commit, and its box has a dashed border. The shapes follow the ISO 5807 flowchart standard, and Mermaid 11.3 or later is needed to draw the bars of async calls. ISO 5807 has no dashed variants, so the dashed border of an imported def and the dashed outline of a def call that isn’t drawn are Jaiph’s own markings.

Steps

Shape Step ISO 5807 symbol What it shows
Start and end Terminator Where a def begins and where it returns.
Parameters Data The def’s parameters, e.g. in: name.
Def call Predefined process A call to another def. A dashed outline, which is Jaiph’s own marking and not part of ISO 5807, means the called def isn’t drawn, as explained in Defs that aren’t drawn.
Script Process A script, an inline script, or one stage of a stdin pipeline.
Prompt Process A prompt sent to an agent.
Send Process A message sent to a channel.
Inbox Stored data Messages that wait until the entry def has finished its own steps. The inbox appears when a def sends to a channel that the entry file routes.
Condition Decision An if or a match. Each arrow out of it is labelled with yes, no, or the match pattern.
Loop Preparation A for … in loop. The next arrow goes back for the next line, and the done arrow leaves the loop.
Join point Connector The point where the arms of a match meet again, or where the entry def starts handling its inbox.
Parallel bar Parallel mode The first bar starts a group of async calls, and the second bar waits until all of them finish.
Failure Terminator A fail step, or a match arm that fails. The workflow stops there.

Arrows

Line Arrow ISO 5807 symbol What it shows
Next step Flow line The step that runs next. A label on the arrow names the branch (yes, no, or a match pattern), the returned value, stdout → stdin between pipeline stages, or async.
recover or catch Dashed line (alternative path) The step failed, so its recover or catch body runs.
retry Flow line The recover body has finished, so the failed step runs again.
↯ channel Communication link A send puts a message in the inbox. The def that sent it doesn’t wait and goes on with its next step.
deliver channel Control transfer The entry def has finished its own steps, so it passes the waiting messages of that channel to the def the channel routes to.

Messages are delivered one channel at a time, in the order in which each channel first got a message. When a def that receives a message sends to another channel, that channel is delivered after the ones before it. Only routes declared in the entry file are used, the same as when the workflow runs, so a message to a channel that is routed only in an imported file is never delivered.

Labels

Defs that aren’t drawn

The chart draws only the defs that are close to the entry def, so a large workflow stays readable. A def that isn’t drawn appears as a call with a dashed outline, and its steps aren’t shown. A def isn’t drawn when any of these is true:

The value all removes a limit, e.g. jaiph graph -d all -i all -l flow.jh draws every def. When the chart leaves defs out, its last line is a comment that counts them and names the flags that would draw them:

%% collapsed: 2 defs beyond --depth 3, 4 library defs (use -d all, -l to expand)

Examples

Each example below is a program from the examples folder of the Jaiph repository, with the chart that jaiph graph prints for it. The Graph tab shows the rendered chart, the next tab shows the source file, and the Mermaid tab shows the command and the text it printed. A test runs the command for every example and fails when the text on this page differs from the output.

One prompt

The smallest workflow sends one prompt and stores the answer in response. The log step isn’t drawn.

export def main() {
  const response = prompt "Say: Hello, I am [model name]!"
  log response
}
jaiph graph hello.jh
flowchart TD
  classDef term fill:#ffffff,stroke:#8a938d,color:#1d2420
  classDef prompt fill:#eee2fd,stroke:#7646d6,color:#381a72

  subgraph g1 ["<b>def</b> main"]
    n1(["start"]):::term
    n2["response = <b>prompt</b> #quot;Say: Hello, I am [model name]!#quot;"]:::prompt
    n3(["end"]):::term
  end

  n1 --> n2
  n2 --> n3

  style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420

say_hello.jh

main calls valid_name, so valid_name gets its own box. The match in valid_name either returns the name or fails, and the prompt in main shows the first line of its text.

#!/usr/bin/env jaiph

# check the name before calling the agent
def valid_name(name_arg) {
  return match name_arg {
    /[A-Z][a-z]+/ => name_arg
    _ => fail "You provided an invalid name :("
  }
}

# jaiph run starts at export def main
export def main(name_arg) {
  const name = valid_name(name_arg)

  # a prompt calls an agent (Cursor by default)
  const response = prompt """
    Say hello to ${name} and provide a fun fact
    about a person with the same name.
    Respond with a single line.
    Do not inspect files or run tools.
  """

  return response
}
jaiph graph examples/say_hello.jh
flowchart TD
  classDef term fill:#ffffff,stroke:#8a938d,color:#1d2420
  classDef fail fill:#fde2e2,stroke:#b42318,color:#7a1a12
  classDef input fill:#fff3d1,stroke:#b7871a,color:#4d3600
  classDef def fill:#dce7fb,stroke:#3563c9,color:#132f66,stroke-width:1.5px
  classDef prompt fill:#eee2fd,stroke:#7646d6,color:#381a72
  classDef decision fill:#f1f2f1,stroke:#5f6762,color:#1d2420

  subgraph g2 ["<b>def</b> valid_name"]
    n4(["start"]):::term
    n5[/"in: name_arg"/]:::input
    n6{"<b>match</b> name_arg"}:::decision
    n7(["<b>fail</b> #quot;You provided an invalid name :(#quot;"]):::fail
    n8(["end"]):::term
  end
  subgraph g1 ["<b>def</b> main"]
    n1(["start"]):::term
    n2[/"in: name_arg"/]:::input
    n3[["name = <b>def</b> valid_name(name_arg)"]]:::def
    n9["response = <b>prompt</b> #quot;Say hello to $#123;name#125; and provide a fun...#quot;"]:::prompt
    n10(["end"]):::term
  end

  n1 --> n2
  n2 --> n3
  n3 --> n4
  n4 --> n5
  n5 --> n6
  n6 -->|"_"| n7
  n6 -->|"/[A-Z][a-z]+/ → name_arg"| n8
  n8 --> n9
  n9 -->|"return response"| n10

  style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  style g2 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420

recover_loop.jh

When check_report_exists fails, the red recover arrow leads to the prompt that creates the report. The retry arrow then goes back to check_report_exists, which runs again.

#!/usr/bin/env jaiph

# a script body goes in '…' or '''…''' quotes
# it is bash by default; for another language, put the
# interpreter before the quotes: node'''…''', python3'''…'''
script check_report_exists = '''
  test -f report.txt
'''

export def main() {
  # when check_report_exists() fails, the recover body runs,
  # and then check_report_exists() runs again (up to 10 times)
  check_report_exists() recover (failure) {
    logerr "Failed to check report.txt"
    prompt "report.txt is missing. Create it with a short dummy summary."
  }

  # a script can also be written inline
  return 'cat report.txt'()
}
jaiph graph examples/recover_loop.jh
flowchart TD
  classDef term fill:#ffffff,stroke:#8a938d,color:#1d2420
  classDef script fill:#e2f1e7,stroke:#3a8657,color:#163b25
  classDef prompt fill:#eee2fd,stroke:#7646d6,color:#381a72

  subgraph g1 ["<b>def</b> main"]
    n1(["start"]):::term
    n2["<b>script</b> check_report_exists()"]:::script
    n3["<b>prompt</b> #quot;report.txt is missing. Create it with a...#quot;"]:::prompt
    n4["<b>script</b> 'cat report.txt'()"]:::script
    n5(["end"]):::term
  end

  n1 --> n2
  n2 -. "<b>recover</b>" .-> n3
  n3 -->|"retry"| n2
  n2 --> n4
  n4 -->|"return"| n5

  style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  linkStyle 1 stroke:#b42318,color:#b42318

agent_inbox.jh

scanner sends a message to findings, and the message waits in the inbox of main. When main has finished its own steps, it delivers findings to analyst. analyst sends to report, so main then delivers report to reviewer.

#!/usr/bin/env jaiph

channel findings -> analyst
channel report -> reviewer

def scanner() {
  log "Scanning for issues..."
  send "Found 3 issues in auth module" -> findings
}

def analyst(msg) {
  send "Summary: ${msg}" -> report
}

def reviewer(msg) {
  logerr "Critical issue: ${msg}"
}

export def main() {
  scanner()
}
jaiph graph examples/agent_inbox.jh
flowchart TD
  classDef term fill:#ffffff,stroke:#8a938d,color:#1d2420
  classDef input fill:#fff3d1,stroke:#b7871a,color:#4d3600
  classDef def fill:#dce7fb,stroke:#3563c9,color:#132f66,stroke-width:1.5px
  classDef send fill:#d8f1ee,stroke:#22857b,color:#0d3a35
  classDef channel fill:#d8f1ee,stroke:#22857b,color:#0d3a35
  classDef join fill:#8a938d,stroke:#8a938d,color:#8a938d

  subgraph g4 ["<b>def</b> reviewer"]
    n12(["start"]):::term
    n13[/"in: msg"/]:::input
    n14(["end"]):::term
  end
  subgraph g3 ["<b>def</b> analyst"]
    n8(["start"]):::term
    n9[/"in: msg"/]:::input
    n10["<b>send</b> #quot;Summary: $#123;msg#125;#quot; → report"]:::send
    n11(["end"]):::term
  end
  subgraph g2 ["<b>def</b> scanner"]
    n3(["start"]):::term
    n4["<b>send</b> #quot;Found 3 issues in auth module#quot; → findings"]:::send
    n6(["end"]):::term
  end
  subgraph g1 ["<b>def</b> main"]
    n1(["start"]):::term
    n2[["<b>def</b> scanner()"]]:::def
    n5[("main inbox")]:::channel
    n7((" ")):::join
    n15(["end"]):::term
  end

  n1 --> n2
  n2 --> n3
  n3 --> n4
  n4 --o|"↯ findings"| n5
  n4 --> n6
  n6 -->|"steps done"| n7
  n8 --> n9
  n9 --> n10
  n10 --o|"↯ report"| n5
  n10 --> n11
  n7 ==>|"deliver findings"| n8
  n12 --> n13
  n13 --> n14
  n11 ==>|"deliver report"| n12
  n14 --> n15

  style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  style g2 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  style g3 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  style g4 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  linkStyle 3 stroke:#22857b,stroke-width:2px
  linkStyle 8 stroke:#22857b,stroke-width:2px

async.jh

main starts two async calls at the first bar, and both calls run at the same time. main waits at the second bar until both calls have finished.

#!/usr/bin/env jaiph

const prompt_text = "Say: Greetings! I am [model name]."

def cursor_say_hello(name) {
  config {
    agent.backend = "cursor"
  }
  const response = prompt "${prompt_text}"
  log response
}

def claude_say_hello(name) {
  config {
    agent.backend = "claude"
  }
  const response = prompt "${prompt_text}"
  log response
}

# main waits until both async calls finish
export def main(name) {
  async cursor_say_hello(name)
  async claude_say_hello(name)
}
jaiph graph examples/async.jh
flowchart TD
  classDef term fill:#ffffff,stroke:#8a938d,color:#1d2420
  classDef input fill:#fff3d1,stroke:#b7871a,color:#4d3600
  classDef def fill:#dce7fb,stroke:#3563c9,color:#132f66,stroke-width:1.5px
  classDef prompt fill:#eee2fd,stroke:#7646d6,color:#381a72
  classDef fork fill:#1d2420,stroke:#1d2420

  subgraph g3 ["<b>def</b> claude_say_hello"]
    n10(["start"]):::term
    n11[/"in: name"/]:::input
    n12["response = <b>prompt</b> #quot;$#123;prompt_text#125;#quot;"]:::prompt
    n13(["end"]):::term
  end
  subgraph g2 ["<b>def</b> cursor_say_hello"]
    n5(["start"]):::term
    n6[/"in: name"/]:::input
    n7["response = <b>prompt</b> #quot;$#123;prompt_text#125;#quot;"]:::prompt
    n8(["end"]):::term
  end
  subgraph g1 ["<b>def</b> main"]
    n1(["start"]):::term
    n2[/"in: name"/]:::input
    n3@{ shape: fork, label: "" }
    n4[["async <b>def</b> cursor_say_hello(name)"]]:::def
    n9[["async <b>def</b> claude_say_hello(name)"]]:::def
    n14@{ shape: fork, label: "" }
    n15(["end"]):::term
  end

  n1 --> n2
  n2 --> n3
  n3 -->|"async"| n4
  n4 --> n5
  n5 --> n6
  n6 --> n7
  n7 --> n8
  n3 -->|"async"| n9
  n9 --> n10
  n10 --> n11
  n11 --> n12
  n12 --> n13
  n8 --> n14
  n13 --> n14
  n14 -->|"all done"| n15

  class n3 fork
  class n14 fork
  style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  style g2 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420
  style g3 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420

stdin.jh

The three scripts form a stdin pipeline, so the output of each script is the input of the next one.

#!/usr/bin/env jaiph

# stdin connects scripts with ->, and the data streams
# from one script to the next without being held in memory
script gen = bash'''
  printf 'alpha\nbeta\ngamma\n'
'''

script upper = bash'''
  tr 'a-z' 'A-Z'
'''

script count = bash'''
  wc -l | tr -d ' '
'''

export def main() {
  # make three lines -> uppercase them -> count them
  const n = stdin gen() -> upper() -> count()
  return n
}
jaiph graph examples/stdin.jh
flowchart TD
  classDef term fill:#ffffff,stroke:#8a938d,color:#1d2420
  classDef script fill:#e2f1e7,stroke:#3a8657,color:#163b25

  subgraph g1 ["<b>def</b> main"]
    n1(["start"]):::term
    n2["stdin <b>script</b> gen()"]:::script
    n3["<b>script</b> upper()"]:::script
    n4["n = <b>script</b> count()"]:::script
    n5(["end"]):::term
  end

  n1 --> n2
  n2 -->|"stdout → stdin"| n3
  n3 -->|"stdout → stdin"| n4
  n4 -->|"return n"| n5

  style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420

say_hello.jh with -d 0

With -d 0 the chart draws only main. The call to valid_name has a dashed outline, and the last line of the Mermaid text names the flag that would draw it.

#!/usr/bin/env jaiph

# check the name before calling the agent
def valid_name(name_arg) {
  return match name_arg {
    /[A-Z][a-z]+/ => name_arg
    _ => fail "You provided an invalid name :("
  }
}

# jaiph run starts at export def main
export def main(name_arg) {
  const name = valid_name(name_arg)

  # a prompt calls an agent (Cursor by default)
  const response = prompt """
    Say hello to ${name} and provide a fun fact
    about a person with the same name.
    Respond with a single line.
    Do not inspect files or run tools.
  """

  return response
}
jaiph graph -d 0 examples/say_hello.jh
flowchart TD
  classDef term fill:#ffffff,stroke:#8a938d,color:#1d2420
  classDef input fill:#fff3d1,stroke:#b7871a,color:#4d3600
  classDef defx fill:#dce7fb,stroke:#3563c9,color:#132f66,stroke-width:1.5px,stroke-dasharray:4 3
  classDef prompt fill:#eee2fd,stroke:#7646d6,color:#381a72

  subgraph g1 ["<b>def</b> main"]
    n1(["start"]):::term
    n2[/"in: name_arg"/]:::input
    n3[["name = <b>def</b> valid_name(name_arg)"]]:::defx
    n4["response = <b>prompt</b> #quot;Say hello to $#123;name#125; and provide a fun...#quot;"]:::prompt
    n5(["end"]):::term
  end

  n1 --> n2
  n2 --> n3
  n3 --> n4
  n4 -->|"return response"| n5

  style g1 fill:#f6f7f6,stroke:#b9c0bb,color:#1d2420

%% collapsed: 1 def beyond --depth 0 (use -d all to expand)