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.
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.
| 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. |
| 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.
name = def valid_name(name_arg). Words that change how a step runs, such as async and stdin, come before the keyword.fail shows the first line of its message. Text longer than 40 characters is cut at the end of a word and ends with .... A named prompt shows its call instead, e.g. prompt review(diff).log, logerr, logwarn, comments, and any const that only stores a plain value.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:
--depth calls away from the entry def. The default is 3. A def that a channel routes to counts as one call away.--import-depth imports away from the entry file. The default is 1, so defs in files that the entry file imports directly are drawn..jaiph/libs/, and the --libs flag isn’t set.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)
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.
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
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
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
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
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
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
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)