jaiph.org · Your first run · Your first agent run · Install & switch versions · Agent Skill · Architecture · CLI · Contributing
Docs note: The Jaiph documentation site follows the Diátaxis framework. Tutorials: Your first run, Your first agent run. How-to: Install & switch versions, Authenticate agent backends, Configure backend & model, Add a hook, Use & publish a library, Save artifacts, Write & run tests, MCP server in 30 seconds, Serve defs over HTTP, Export traces to an OTLP collector, Deploy jaiph. Reference: CLI, Configuration, Grammar, Language, Environment variables. Explanation: Why Jaiph, Architecture, Inbox & Dispatch, Async Handles. Contributor: Contributing, Agent Skill.
Open Source · Powerful · Friendly
Jaiph is a small language and a runtime for jobs that mix AI agents with ordinary scripts in Bash, Python, Node, or another language. When you give an agent a job with several steps, the agent decides the steps again on every run. In Jaiph you write the steps in a .jh file: a script does the exact work, a prompt calls an agent where a step needs judgment, and a def puts the steps in order. Jaiph runs the steps, saves what each step printed, and stops with a clear error when a step fails.
jaiph graph draws the steps of a file as a flowchart without running anything (Execution flow). The CLI checks the whole file before it runs the first step.
Warning
Jaiph is still in an early stage. Expect breaking changes.
- Defs — Compose
prompt, bare calls, channel sends, conditionals,asynccalls with implicit join,catch, and repair-and-retryrecover.jaiph runenters atexport def main. - Scripts —
scriptsteps run bash or polyglot code as subprocesses. - Agents — Backends include Cursor, Claude, Codex (HTTP), or a custom
agent.command. - Testing —
*.test.jhfiles run in-process (jaiph test) with mocks andexpect_*assertions (Write & run tests). - Safety and inspectability — live
__JAIPH_EVENT__on stderr and durable.jaiph/runs/artifacts (Architecture). Isolation of the process from the rest of the machine is an outer concern: wrapjaiphin your own container, pod, or CI runner if you want a sandbox (Deploy jaiph). - Tooling —
jaiph compile,jaiph format,jaiph install/.jaiph/libs/(Use & publish a library), and optionalhooks.json(CLI, Add a hook). - MCP server —
jaiph mcp ./tools.jhserves a file's exported defs as MCP tools over stdio, so any MCP client (Claude Code, Cursor) can call tested Jaiph defs as tools (MCP server in 30 seconds). - HTTP API —
jaiph serve ./tools.jhserves the same defs over HTTP with a generated OpenAPI 3.1 document and a browser Swagger UI at/docs, so any HTTP client (CI, Kubernetes, another service) can invoke them and inspect runs. Production auth is either a static single-operator bearer token or OIDC/JWT with per-user identity andinvoke/inspect/cancelscope authorization, and every run is audit-attributed to its principal and correlation id (Serve defs over HTTP). - OpenTelemetry — set the standard
OTEL_EXPORTER_OTLP_ENDPOINTand each run exports one span tree (run → steps → prompts) to any OTLP collector — Grafana Tempo, Honeycomb, Datadog. Host-side, end-of-run, credential-redacted, zero new dependencies, never load-bearing (Export traces to an OTLP collector). - Sentry error reporting — set the standard
SENTRY_DSNand every failed run (nonzero exit or a signal) is pushed to Sentry as one error event — def, failing step, a redacted output excerpt, and a run-dir pointer — so operators get alerting and grouping without scraping run dirs. Host-side, redacted, zero new dependencies, never load-bearing; successful runs send nothing (Report failed runs to Sentry).
- CLI (
src/cli) —jaiph run/test/compile/graph/format/init/install/use/mcp/serve; prepares scripts, spawns the def runner(or in-process test runner), parses__JAIPH_EVENT__on stderr, runs hooks onjaiph runonly. - Parser (
src/parser.ts,src/parse/*) —.jh/.test.jh→ AST. - Validator (
src/transpile/validate.ts) — imports and symbol references at compile time. - Transpiler (
src/transpile/*) — emits atomicscriptfiles underscripts/only (no def-level shell). - Node runtime (
src/runtime/kernel/node-workflow-runtime.ts,graph.ts) — interprets the AST;buildRuntimeGraph(graph)consumes theModuleGraphproduced byloadModuleGraph(no filesystem reads). - Node test runner (
src/runtime/kernel/node-test-runner.ts) —*.test.jhblocks with mocks. - JS kernel (
src/runtime/kernel/) — prompts, managed scripts,__JAIPH_EVENT__, inbox, mocks. Diagrams, runtime contracts, on-disk artifact layout, and distribution: Architecture. Test layers and E2E policy: Contributing.
Run a sample program without installing anything first:
curl -fsSL https://jaiph.org/run | bash -s '
export def main() {
const response = prompt "Say: Hello I'\''m [model name]!"
log response
}'Requires curl. The script installs Jaiph automatically if needed.
curl -fsSL https://jaiph.org/install | bashOn Windows, install with PowerShell instead (installs jaiph-windows-x64.exe to %LOCALAPPDATA%\jaiph\bin):
irm https://jaiph.org/install.ps1 | iexOr install from npm:
npm install -g jaiphIn GitHub Actions, install a pinned CLI with the setup-jaiph composite action (same release binaries, no Node required on the runner):
- uses: jaiphlang/jaiph/actions/setup-jaiph@v0.16.0
with:
version: 0.16.0 # semver, a release tag, or 'nightly'
- run: jaiph --version # jaiph is now on PATH for later stepsVerify: jaiph --version. Switch versions: jaiph use nightly or jaiph use 0.16.0.
Releases ship a SHA256SUMS file plus a detached minisign signature (SHA256SUMS.minisig). The installer verifies the checksum and requires a valid signature. A missing minisign aborts the install on every host, including CI, rather than degrading to checksum-only. The setup-jaiph action installs minisign on the runner so CI installs stay signed. For a deliberate checksum-only install, set JAIPH_ALLOW_UNSIGNED=1. See Verify the release signature.
Initialize a project (optional): jaiph init writes .jaiph/ with a bootstrap file, gitignore entries for runs/tmp, and SKILL.md. The CLI resolves the skill body in this order — JAIPH_SKILL_PATH, install-relative jaiph-skill.md, docs/jaiph-skill.md under cwd, then an embedded copy baked into the binary as the final fallback — so jaiph init always writes SKILL.md (see Install & switch versions). Canonical skill text for agents: https://raw.githubusercontent.com/jaiphlang/jaiph/refs/heads/main/docs/jaiph-skill.md.
- Run
export def main:jaiph run path/to/main.jh [args...]or./main.jh [args...]with a#!/usr/bin/env jaiphshebang. - Run tests:
jaiph test(workspace),jaiph test ./dir, orjaiph test path.test.jh. - Validate without executing:
jaiph compile …(runs the same compile-time validation asjaiph run, but collects every error at once instead of stopping at the first; noscripts/emission — see Architecture). - Format sources:
jaiph format …/jaiph format --check ….
Full flags and environment variables: CLI, Environment variables. New here? Start with Your first run.
#!/usr/bin/env jaiph
script check_deps = 'test -f "package.json"'
def deps_exist() {
check_deps() catch (err) {
fail "Missing package.json"
}
}
export def main(task) {
deps_exist()
const ts = 'date +%s'()
prompt "Build the application: ${task}"
}
./main.jh "add user authentication"For the full language reference, see Grammar and Language. For install, libraries, hooks, testing, and artifacts, see the How-to quadrant: Install & switch versions, Use & publish a library, Add a hook, Write & run tests, Save artifacts. New to Jaiph? Start with the tutorials: Your first run and Your first agent run. Or visit jaiph.org.
- AI agent who wants to work in a predictable, structured way? Read the Agent Skill — it teaches you how to author Jaiph programs and makes your behavior verifiable and auditable.
- Human who manages agents and wants reliable, repeatable automation? See the Samples and Your first run.
- Contributor who wants to improve Jaiph itself? See Contributing.
See Contributing for branch strategy, pull requests, the test layers, and code style. Use GitHub Issues for bugs and feature discussion.
