Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

Getting started

Install Harn, run an agent, call a tool, and replay a recorded model response. This tutorial uses synthetic responses, so you don't need provider credentials.

Install Harn#

macOS and Linux#

curl -fsSL https://harnlang.com/install.sh | sh

The installer downloads the release for your operating system and CPU. To install a particular release, set HARN_VERSION to its release tag. Releases ship as .tar.xz; on Linux the installer needs xz (package xz-utils on Debian and Ubuntu, xz on Fedora and Alpine). Releases through v0.10.178 ship .tar.gz and need the install.sh from their own tag. The installer retains project licenses and third-party notices in harn-licenses/ beside the binary, including at custom HARN_INSTALL_DIR destinations. It refuses releases with missing, empty, or invalid legal files before changing an existing installation.

Windows#

Run this command in PowerShell:

irm https://harnlang.com/install.ps1 | iex

From source#

See Contributing for source builds and development prerequisites. This tutorial uses the installed release.

Check the installation:

harn --version

Create a project#

The project generator creates a harn.toml, a program, a library directory, and a test directory.

harn init hello-harn
cd hello-harn

The generated .gitignore keeps local run history out of commits. Source and test fixtures remain trackable. Existing ignore files are preserved. Initialization reports conflicting paths or write failures and exits unsuccessfully; it keeps existing files and any files already created so you can inspect them.

Replace main.harn with:

import { agent_loop } from "std/agent/loop"
import { AgentSpec } from "std/agent/options"

fn main(harness: Harness) {
  const options: AgentSpec = {provider: "mock", max_iterations: 2}
  harness.stdio.println("Running: Say hello.")
  const result = agent_loop(harness, "Say hello.", nil, options)
  harness.stdio.println(result.status)
  harness.stdio.println(result.visible_text)
}

Run it:

harn run main.harn
Running: Say hello.
done
Mock response to 2-word prompt: Say hello.

The loop accepts a task, optional system prompt, and options. max_iterations bounds model requests; done means the loop completed. The mock provider supplies deterministic output without a model request. It doesn't measure how well a real model follows your instructions.

Check your program#

Run these commands before you commit:

harn fmt main.harn
harn check main.harn
harn lint main.harn

fmt applies the formatter. check validates syntax and types. lint finds common problems and style issues.

Call a tool#

Get the runnable examples without building Harn from source:

git clone --depth 1 https://github.com/burin-labs/harn.git harn-examples
cd harn-examples/examples/first-hour
harn run tools.harn --llm-mock tools.jsonl
tool: 2 + 3 = 5
done
2 + 3 = 5.

Open tools.harn. The add tool declares integer inputs and an integer result. The fixture requests the tool, Harn calls the handler, and the next model response ends the loop. The tool: line comes from the handler itself. This tool only calculates a sum. File and process effects require the corresponding harness capabilities.

Record and replay#

From the same directory:

harn run record-replay.harn --llm-mock-record responses.jsonl
harn run record-replay.harn --llm-mock responses.jsonl

Each command prints:

Mock response to 2-word prompt: Say hello.

The first command records a synthetic response. The second supplies that recording through the model-call interface. It doesn't recreate the filesystem or replay tool effects. Keep recordings local until you've checked them for sensitive data. Delete responses.jsonl to discard this recording.

Use a real model#

Follow Configure a provider to choose a local or hosted model and set its credentials. Replace the example's provider: "mock" options with that route, and omit --llm-mock when you want a real request. Keep credentials out of Harn source and version control.

Continue with Agent loops for tools and execution limits, or Language basics for syntax.