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

What is Jaiph?

Jaiph is a composable scripting language and runtime for defining and orchestrating AI agent programs. You write .jh files that combine def, script, and prompt into executable pipelines. The CLI parses source into an AST, validates references at compile time, and the Node runtime interprets the AST directly.

Warning

Jaiph is still in an early stage. Expect breaking changes.

Features

• Defs — Compose prompt, run, channel sends, conditionals, run async with implicit join, catch, and repair-and-retry recover. jaiph run enters at export def main.
• Scripts — script steps run bash or polyglot code as subprocesses.
• Agents — Backends include Cursor, Claude, Codex (HTTP), or a custom agent.command.
• Testing — *.test.jh files run in-process (jaiph test) with mocks and expect_* 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: wrap jaiph in 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 optional hooks.json (CLI, Add a hook).
• MCP server — jaiph mcp ./tools.jh serves 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.jh serves 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 and invoke / inspect / cancel scope authorization, and every run is audit-attributed to its principal and correlation id (Serve defs over HTTP).
• OpenTelemetry — set the standard OTEL_EXPORTER_OTLP_ENDPOINT and 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_DSN and 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).

Core components

• CLI (src/cli) — jaiph run / test / compile / format / init / install / use / mcp / serve; prepares scripts, spawns the def runner(or in-process test runner), parses __JAIPH_EVENT__ on stderr, runs hooks on jaiph run only.
• 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 atomic script files under scripts/ only (no def-level shell).
• Node runtime (src/runtime/kernel/node-workflow-runtime.ts, graph.ts) — interprets the AST; buildRuntimeGraph(graph) consumes the ModuleGraph produced by loadModuleGraph (no filesystem reads).
• Node test runner (src/runtime/kernel/node-test-runner.ts) — *.test.jh blocks 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.

Quick try

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.

Install

curl -fsSL https://jaiph.org/install | bash

On Windows, install with PowerShell instead (installs jaiph-windows-x64.exe to %LOCALAPPDATA%\jaiph\bin):

irm https://jaiph.org/install.ps1 | iex

Or install from npm:

npm install -g jaiph

In 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.13.0
  with:
    version: 0.13.0        # semver, a release tag, or 'nightly'
- run: jaiph --version     # jaiph is now on PATH for later steps

Verify: jaiph --version. Switch versions: jaiph use nightly or jaiph use 0.13.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.

Usage

• Run export def main: jaiph run path/to/main.jh [args...] or ./main.jh [args...] with a #!/usr/bin/env jaiph shebang.
• Run tests: jaiph test (workspace), jaiph test ./dir, or jaiph test path.test.jh.
• Validate without executing: jaiph compile … (runs the same compile-time validation as jaiph run, but collects every error at once instead of stopping at the first; no scripts/ 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.

Example

#!/usr/bin/env jaiph

script check_deps = `test -f "package.json"`

def deps_exist() {
  run check_deps() catch (err) {
    fail "Missing package.json"
  }
}

export def main(task) {
  run deps_exist()
  const ts = run `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.

Start here

• 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.

Contributing

See Contributing for branch strategy, pull requests, the test layers, and code style. Use GitHub Issues for bugs and feature discussion.

License

Apache License 2.0.