Harn

Harn is a programming language and runtime for building AI agents.

You define the task, prompts, tools, and rules. Harn runs the conversation between the model and your tools, enforces permissions, and saves the history of the work. It handles differences between model providers so your application can use the same agent code with local or hosted models.

Use Harn when your application needs an agent to take several steps: investigate a failed job, review a change, or play a game. For example, 20eq is a 20 Questions game written in Harn, and Burin uses Harn in its coding workbench.

Harn is pre-1.0. The language, standard library, and CLI can change between releases. See the release notes and changelog before upgrading.

Where Harn fits

flowchart TD
    accTitle: How Harn connects an application to models and tools
    accDescr: Your application supplies a Harn program. The runtime exchanges requests and results with models and tools and saves the run history.
    App["Your application<br/>game, coding tool,<br/>or service"]
    Program["Your Harn program<br/>task and prompts,<br/>tools and rules"]
    Runtime["Harn runtime<br/>agent loop<br/>and permissions"]
    Models["Language models<br/>local or hosted"]
    Tools["Your tools<br/>files, APIs,<br/>and databases"]
    History["Saved run history<br/>inspect, replay,<br/>and evaluate"]
    App --> Program
    Program --> Runtime
    Runtime <--> Models
    Runtime <--> Tools
    Runtime --> History

Your application supplies its own behavior and interface. Harn manages the model calls, tool requests, and execution state underneath it. You choose which tools the agent can use and what those tools may access.

An agent in Harn

This agent reads a project's README and summarizes it. Its only tool reads files; the task doesn't require it to edit code or run commands.

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

fn main(harness: Harness) {
  tool read_project_file(path: string) -> string {
    description "Read a file in the project"
    return harness.fs.read_text(path)
  }
  const options: AgentSpec = {
    loop_until_done: true,
    tools: read_project_file,
    max_iterations: 8,
  }
  const result = agent_loop(
    harness,
    "Read README.md and summarize what this project does.",
    "Ground your answer in the files you read. Cite their paths.",
    options,
  )
  harness.stdio.println(result.status)
  harness.stdio.println(result.visible_text)
}

The loop asks the model what to do, runs the requested tool, and returns its result to the model. It stops when the task ends or a limit is reached. The returned status distinguishes completion from errors and exhausted budgets.

Save the example as main.harn in a project with a README. After configuring a model, run harn run main.harn. Hosted models need the provider's credentials and may incur charges. The agent-loop guide covers tools, limits, and longer conversations.

Tool annotations can describe whether a tool only reads data or interacts with external systems. These hints describe intent; capability permissions enforce access. See the annotated tool example and annotation reference.

Try Harn

Install the release binary on macOS or Linux:

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

The installer verifies release checksums and installs the tools for your platform. See getting started for Windows, source builds, and your first project. For a pinned version in automation, use the bootstrap guide.

You can try the bundled demos without an API key:

harn demo --list
harn demo merge-captain

These demos replay recorded model responses. They show the workflow without calling a provider. Use the getting-started tutorial to set up a real model and create your own project.

See what happened

A saved run history helps answer practical questions: which tool failed, what the model saw, and where the agent stopped. Harn calls the JSON index for that history a run record. It links the execution's events, results, and artifacts.

Open the local portal to inspect your runs:

harn portal

The portal guide shows the timeline, model calls, token use, and reported cost. The debugging guide explains how to investigate failures. Replay lets you investigate recorded execution, and sessions let you continue agent work across calls. The available history and recovery options depend on what the run recorded.

What Harn handles

Harn owns execution and its history. Your application owns its interface, approval presentation, and how changes appear to people, including undo and redo. See the mental model for the design, and sandboxing for the permission boundary.

Learn more

• Start building: first workflow, code review agent, or MCP server.
• Connect a host: editor integration, MCP, ACP, and A2A, and deployment on Fly.io.
• Look up an API: language basics, CLI reference, prompt-cache reports, and builtins.
• Explore the design: why Harn, workflow execution, and glossary.

The full documentation is at harnlang.com.

Contribute

Harn is written in Rust. The repository also contains its standard library, formatter, language server, debugger, editor grammar, and documentation.

See CONTRIBUTING.md for setup, checks, and pull requests. Maintainer commands live in the release guide.

Harn is available under the Apache 2.0 or MIT license.