Skip to main content
Glama

Hirð

The king's hirð wading a river, drawn by Erik Werenskiold

A hirð is a Norse king's household guard: sworn retainers, each with a named duty, answerable to one lord. Illustration by Erik Werenskiold for Magnús Erlingsson's saga in Snorri's Heimskringla (public domain, via Wikimedia Commons).

A typed language for long-running agent systems on BEAM: effect-row tracking, auditable tool effects, typed actors, and OTP supervision. Python agent frameworks hide side effects in coroutine soup; Hirð makes every tool call, every actor message, and every supervisor boundary visible in the types and queryable by tooling.

What that buys: deterministic replay of real agent traffic. Every tool call is recorded unconditionally in a canonical wire format, so a recorded run is a file you can replay — the same calls, in the same order, each served the result the recorded run got back, with no service contacted. That is a regression test with no oracle to maintain, a bug report that reproduces, and a fixed environment to evaluate a change in. It is also not something you can retrofit onto a framework that hides its side effects: it needs the effects in the types and a single dispatch path underneath them. hird demo is that claim in one command: it records a run of the demo planner, replays that one recording against three variants of the program, and prints where each parted from it.

And systems that stand. A Hirð program is not a script that exits: fn main can start a supervision tree and stand, leaving typed actors serving after its own work is done — driving their own periodic rounds off a clock capability, crashing and restarting under a declared budget, every round on the audit stream. hird run demo/agent_fleet is that claim running: a hirð of three retainers that keeps working through a deliberate crash.

Status: pre-1.0 and experimental. The v0.1 compiler pipeline works end to end (the demos below type-check, compile to Erlang, and run on BEAM), but the language surface is unstable, nothing is published to crates.io, and breaking changes land without deprecation cycles. The roadmap lives in the in-repo issue tracker (see .beads/README.md).

Install

Prebuilt binaries for Linux, macOS, and Windows are attached to every release: extract the archive for your platform and put hird (the compiler), hird-lsp, and hird-mcp on your PATH.

From source, with Rust 1.97 or newer:

cargo install --git https://github.com/no-materials/hird hird-cli
cargo install --git https://github.com/no-materials/hird hird-lsp  # optional
cargo install --git https://github.com/no-materials/hird hird-mcp  # optional

With Nix, the same three binaries are flake outputs (nix run github:no-materials/hird#hird-mcp).

Compiling and running programs needs Erlang/OTP on PATH (apt install erlang, brew install erlang, …); hird check works without it.

Related MCP server: codelattice

Quick start

Hirð has no ambient print. Anything a program tells the outside world goes through a tool — a declared, typed, audited external operation — so the smallest observable program is a tool call. Save this as hello.hird:

module Hello

tool Say : { message: String } → ()

fn quiet_say(args: { message: String }) → () = ()

fn main() → () ! {} =
  handle {
    Tool<Say> → quiet_say,
  } in say({ message: "hello, world" })
hird run hello.hird
{"schema_version":1,"tool":"Say","args":{"message":"hello, world"},"result":{"ok":null},"timestamp":"…","caller":"Hello.main@main"}

Three things happened. Declaring tool Say created the effect Tool<Say> and a callable say. The handle block supplied an implementation and discharged that effect, so main is honestly ! {}. And the call was recorded on the audit stream — unconditionally, because mocked and real tool calls audit identically. ASCII operator spellings (->) normalise to their Unicode forms (→) at lex time, so either is legal input.

Command

What it does

hird check <file-or-dir>

type- and effect-check; coded diagnostics

hird build <file-or-dir>

emit readable Erlang, compile it to .beam

hird run <file-or-dir>

build, then execute fn main on BEAM

hird demo

record one run of the built-in demo, replay it against variants of the program

hird emit-ast <file> --json

the typed IR of every definition

hird emit-effect-graph <file-or-dir> --json

actors, mailboxes, handler rows, supervisors, tools, function rows

hird effect-diff --exact <baseline.json> <file-or-dir>

fail when the effect graph drifts from a committed baseline

docs/writing-hird-human.md is the guided tour, and phrasebook.md the dense syntax reference.

The flagship demo: a standing hirð of agents

A hirð is retainers with named duties; demo/agent_fleet/ is the metaphor made literal. Three supervised actors serve for as long as the program stands: a Planner ticks itself on a clock and forges each round's order (pure planning imported from a second module — the source spans a real use boundary), an Executor carries the order out through Tool<RunErrand> and reports onward, an Auditor chronicles every outcome through Tool<Chronicle>. Round 3 crashes the executor on purpose: FleetSup restarts rest_for_one, so the auditor — downstream of the crash — restarts with it, the planner keeps its round counter, and the rounds keep coming. Actor state dies with its process; the audit stream is the durable record.

hird run demo/agent_fleet
{"schema_version":1,"tool":"RunErrand","args":{"errand":"mend the palisade","round":2},"result":{"ok":"done"},"timestamp":"…","caller":"Executor.handle_msg/Carry@FleetSup/executor"}
{"schema_version":1,"tool":"Chronicle","args":{"note":"done","round":2},"result":{"ok":null},"timestamp":"…","caller":"Auditor.handle_msg/Record@FleetSup/auditor"}
{"schema_version":1,"tool":"Log","args":{"level":"info","message":"executor takes its post"},"result":{"ok":null},"timestamp":"…","caller":"Executor.init@FleetSup/executor"}
{"schema_version":1,"tool":"Log","args":{"level":"info","message":"auditor takes its post"},"result":{"ok":null},"timestamp":"…","caller":"Auditor.init@FleetSup/auditor"}
{"schema_version":1,"tool":"RunErrand","args":{"errand":"scout the border","round":4},"result":{"ok":"done"},"timestamp":"…","caller":"Executor.handle_msg/Carry@FleetSup/executor"}

Round 3 never beats — the crash consumed its order — and the two re-posted inits are the supervisor's work, visible in the same stream as everything else. The tree itself is queryable; its effect graph is the system's live org chart, every retainer with its duty and its effects:

hird emit-effect-graph demo/agent_fleet

Record and replay a run

demo/agent_planner.hird drives one planning round against a supervised Planner: repository state in through Tool<ReadRepo>, pure analysis, tickets out through Tool<CreateTicket>, progress through Tool<Log>. Every tool invocation — mocked or real — lands on the audit stream, one canonical JSON line per call:

{"schema_version":1,"tool":"CreateTicket","args":{"body":"The parser has no fuzz harness.","title":"Fuzz the parser"},"result":{"ok":{"ctor":"TicketId","args":["Fuzz the parser"]}},"timestamp":"2026-07-28T06:44:42.893Z","caller":"AgentPlanner.file_tickets@PlannerSup/planner"}

Because the stream is complete — every call, full arguments, tagged result — a recorded run is a replayable environment:

hird run demo/agent_planner.hird --audit-file run.jsonl   # record
hird run demo/agent_planner.hird --replay run.jsonl       # replay

The replay cursor outranks every handle and install block, so no tool runs and no service is contacted; each call receives its logged result, failures included. Matching is strict: the call at each position must be the one the log recorded there, or the run crashes with a replay_divergence naming the position, the recorded call and the offered one — and a log the run did not read to the end fails too.

So a checked-in recording is a regression test with no oracle to maintain: demo/agent_planner.golden.jsonl is one run of the planner, replayed by the demo suite in CI, and the build fails the moment the program's decisions drift from it. And because the log serves every result, one recording is a fixed environment to compare variants of a program in — every arm meets a byte-identical world, so what differs is attributable to the programs:

baseline        agreed with all 7 calls
announce-first  parted at call 2 (tool_mismatch)
eager           parted at call 4 (args_mismatch)

That evaluation is hird demo: no arguments, nothing to install beyond Erlang, and nothing checked in that it has to be trusted about — it writes the planner and the two edited variants into _build/hird-demo, records the episode itself, and replays it against all three.

docs/audit-evidence.md states what the stream guarantees and what it does not; docs/tool-effects.md is the normative format and replay specification.

LLM tooling (MCP)

hird-mcp on Glama

hird-mcp is a Model Context Protocol server over the same compiler pipeline, speaking stdio. It gives LLM agents structured compiler queries instead of source-reading guesswork: check_file (every diagnostic of a program, warnings included), list_definitions (a module outline with per-symbol token costs), infer_type, lookup_definition, explain_effect_row, render_ir_fragment, explain_actor_protocol, emit_actor_effect_graph, get_context_for_symbol (token-budget-aware symbol summaries), and get_context_budget. Errors come back structured — undefined names list the available ones, parse and type errors carry coded diagnostics — so agents can self-correct from tool output alone. The server is self-describing: it serves the agent-facing writing guide, the parser code index, and the phrasebook as MCP resources, and one prompt (author_supervised_module) that scripts the write-then-verify loop.

The repository ships a project-scoped .mcp.json, so Claude Code sessions started here pick the server up automatically (it launches nix run .#hird-mcp; run nix build .#hird-mcp once so the first session start doesn't wait on a cold build). Any other MCP client can launch the hird-mcp binary directly, with no arguments.

Things worth asking an agent wired to it:

  • "What does the Planner actor in demo/agent_planner.hird do? Ask the compiler instead of reading the source."

  • "If the Executor in demo/agent_fleet crashes mid-round, who restarts it, who restarts with it, and what's the restart budget?"

  • "Give me a 50-token summary of the Planner actor. Now 400 tokens. What got dropped?"

  • "Write a new Hirð module with a supervised actor, and iterate with the hird tools until they confirm it's clean."

demo/counter_demo.hird is that last prompt's output: a supervised counter written by an LLM agent that verified itself against the MCP tools alone — it type-checks and runs on BEAM unmodified. And demo/heartbeat.hird is the smallest standing program: one actor, one clock, one beat a second until Ctrl-C. docs/writing-hird-llm.md is the agent-facing guide, and docs/context-packing.md shows the third prompt answered for real: the Planner at 50 and 400 tokens, and what each budget dropped.

Editor support

hird-lsp is a Language Server Protocol server over the compiler front end, speaking stdio: diagnostics on open and save, hover with inferred types and effect rows, go-to-definition for top-level declarations. Point any LSP client at the binary, with no arguments. tree-sitter-hird/ is a tree-sitter grammar for the v0.1 surface, with highlight, indent, and fold queries, built by the flake as a package output. docs/editor-setup.md has client configuration (including Neovim, with and without nix), the grammar development loop, and the v0.1 limitations.

Repository layout

  • crates/ — the Rust compiler workspace (lexer, parser, checker, IR, codegen, CLI, LSP and MCP servers, benchmark runner).

  • tree-sitter-hird/ — the tree-sitter grammar and editor queries.

  • runtime/ — the hand-written Erlang runtime support library (tool dispatch, audit sink, handler registry).

  • demo/ — the v0.1 demo programs.

  • conformance/ — golden files for the audit-log wire format.

  • docs/ — normative specifications (grammar, error model, tool effects wire format, effect graph), the audit stream's guarantees, and editor setup.

  • phrasebook.md — dense surface-syntax reference.

  • DECISIONS.md — architecture decision records.

  • .beads/README.md — the issue tracker and roadmap, driven by bd.

Development

MSRV is Rust 1.97 (edition 2024). Before sending changes:

cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features

BEAM-dependent tests skip themselves when erlc is not on PATH.

CONTRIBUTING.md has the rest: the dev shell, the checks CI runs beyond those three, what "done" means, and how to report a bug or file an issue from outside the repository.

License

Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Available Tools

10 tools
check_fileCheck programA
Read-onlyIdempotent

Check a .hird file's whole program and return every diagnostic, warnings included. Use it as the first and last step of an edit: nothing else reports a warning, and the other tools fail on the first error instead of listing them all. Returns ok (no diagnostic of severity Error anywhere in the program) and diagnostics across every file of the directory, each with file, a stable code (P… parse, C… check, both documented in docs/writing-hird-llm.md), severity, message, nullable help, a 1-based character position (line/column to an exclusive end_line/end_column), and related locations in the same file. Parse and type errors are results here, never isError. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required). Returns: ok, file, diagnostics

emit_actor_effect_graphEmit actor effect graphA
Read-onlyIdempotent

Emit the actor/effect graph rooted at one actor: every actor reachable through Send, Await, Spawn, and Schedule effects (matched by message type), every supervisor of an included actor together with its whole child set, and every tool an included actor's effect summary names. Use it for 'what does this actor transitively do or depend on'; effect rows are per-process, so no single signature shows this. Use explain_actor_protocol for one actor's own interface and get_context_budget to gauge the size before requesting it. The reach spans the whole program: a row's type names resolve through the naming module's imports, so a sibling module's actors, supervisors, and tools are included and same-named declarations in two modules stay distinct. Returns schema_version (1), module (the root's), root, and the included actors, supervisors, and tools, whose nodes share the shape of hird emit-effect-graph --json plus a module tag; declarations the root does not reach are omitted. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required), actor_name (required). Returns: root, tools, actors, module, +2 more

explain_actor_protocolExplain actor protocolA
Read-onlyIdempotent

Describe one actor's protocol: its message type and constructors, state type, init parameters and effects, per-handler effect rows, and the declared effect summary. Use it to learn how to talk to an actor or what each handler may do; use emit_actor_effect_graph for the actors, supervisors, and tools it reaches transitively, and lookup_definition if you only need its location. Returns actor with name, line, state, message (name, constructors), init (params, effects), handlers (message, effects), and effects; types and rows carry a display string. actor_name resolves like any symbol: a local actor, a selectively imported one, or Qualifier.name through a use; module and file name the defining module. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required), actor_name (required). Returns: file, actor, module

explain_effect_rowExplain effect rowA
Read-onlyIdempotent

Explain a function's effect row: the canonical row plus a one-sentence explanation of each effect. Use it for 'what may this function do' or to interpret an unfamiliar effect. It covers one named function (a tool name explains the tool's generated function, Tool<Name> included); use infer_type for an arbitrary expression's row and emit_actor_effect_graph for what an actor transitively does. Returns name (the function explained), type, effect_row, open (the row ends in a row variable, so it may carry more effects than listed), pure (closed and empty), and effects, each with effect and explanation. A name that is not a function (a type, an actor, …) is not_a_function; an unknown name is not_found with the available names in error.data.available. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required), fn_name (required). Returns: file, name, open, pure, +3 more

get_context_budgetEstimate context budgetA
Read-onlyIdempotent

Estimate the token cost of loading a file's declarations into an LLM context window, per category: types, effects, actors, supervisors, tools, and function signatures. Use it before pulling a module in wholesale, to choose between get_context_for_symbol calls and a full read, or to pick a budget; it names no individual symbols. Returns approx_tokens with types, effects, actors, supervisors, tools, functions, and total, estimated at ~4 characters per token from one-line signatures, and a note restating that. Fails only when the file is unreadable or has parse or type errors. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required). Returns: file, note, module, approx_tokens

get_context_for_symbolSummarize symbol for contextA
Read-onlyIdempotent

Summarize one symbol for an LLM prompt within an approximate token budget: signature, effect row, doc comment, callers, and callees, added in that order while they fit. Use it as the default way to bring a symbol into context; use lookup_definition for just the location, explain_effect_row for effect explanations, and render_ir_fragment for the full body. Returns kind, the budget applied, summary (prompt-ready text), approx_tokens (its estimated cost at ~4 characters per token), and omitted (the sections that did not fit). The signature is always present, truncated when the budget is smaller than it. An unknown name is not_found with the available names in error.data.available. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required), name (required), budget. Returns: file, kind, budget, symbol, +3 more

infer_typeInfer expression typeA
Read-onlyIdempotent

Infer the type and effect row of the expression at a source location (1-based line and character column) in a .hird file. Use it for 'what is the type here', including local bindings, sub-expressions, and names inside use lists; for a named top-level definition prefer lookup_definition, and for a function's effects with explanations prefer explain_effect_row. Returns token (the source token found at the location), type (the normalized type as Hirð prints it), and effect_row (the row of a function-typed expression, {} otherwise). A location outside the file is invalid_params; one with no typed expression is not_found. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required), line (required), column (required). Returns: file, line, type, token, +2 more

list_definitionsOutline moduleA
Read-onlyIdempotent

Outline a .hird module: every name its top-level declarations bind, in source order, plus its imports. Use it to orient in a module before choosing which symbols to pull in with get_context_for_symbol; it is cheap (no bodies, no effect graph) and the only tool that names a module's symbols without a failed lookup. Returns module, imports (each with the imported module as written, its defining file, the qualifier a whole-module import binds or null, and the members a selective import binds unqualified), and definitions, each with name, kind (the kinds lookup_definition reports: a type also lists each constructor, a tool its generated tool_function, an actor its message_type and each message_constructor), line, a one-line signature, nullable doc, and approx_tokens (the signature's estimated cost at ~4 characters per token, so a get_context_for_symbol budget of at least that keeps the signature whole). Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required). Returns: file, module, imports, definitions

lookup_definitionLook up definitionA
Read-onlyIdempotent

Look up a top-level definition by name: defining file and line, kind, type, and doc comment. Use it first to locate or identify a symbol; use get_context_for_symbol when you also want effects, callers, and callees, explain_effect_row to interpret a function's effects, and render_ir_fragment for its body. Returns kind (function, type, type alias, constructor, effect, tool, tool_function, actor, message_type, message_constructor, supervisor, or extern), line, and nullable type (for a type alias, the type it expands to) and doc; file is the sibling module when the name is imported. An unknown name is not_found, with every name in the file's scope in error.data.available. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required), name (required). Returns: doc, file, kind, line, +2 more

render_ir_fragmentRender IR fragmentA
Read-onlyIdempotent

Render the typed intermediate representation (IR) of one top-level definition as JSON. Use it when the exact lowered structure matters: desugared bodies, the resolved type on every node, a tool's generated function. The IR is verbose and follows the compiler's declaration serialization, so for a human-oriented view prefer get_context_for_symbol or lookup_definition. Returns module, name, and ir (the serialized declaration). An unknown name is not_found with the available names in error.data.available; a type alias is no_ir (aliases are expanded before lowering) with its expansion in error.data.expansion. Read-only: compiles the file's directory in memory (cached until a sibling changes) and writes or executes nothing. Failures are isError results with a stable error.code: file_not_found, read_error, invalid_params, and, for every tool but check_file, parse_error or check_error carrying coded diagnostics in error.data.diagnostics (the shape check_file returns).

Inputs: file (required), name (required). Returns: ir, file, name, module

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: whole-program diagnostics, module outlines, expression types, definition lookup, effect explanations, IR rendering, actor protocols, actor graphs, and context budgeting. The cross-references in the descriptions make the boundaries explicit, so an agent can reliably choose the right tool.

    Naming Consistency5/5

    All tool names follow a strict verb_noun snake_case pattern (check_file, list_definitions, infer_type, lookup_definition, explain_effect_row, render_ir_fragment, explain_actor_protocol, emit_actor_effect_graph, get_context_for_symbol, get_context_budget). Verbs are specific and the object is consistently a noun, making the naming predictable and scannable.

    Tool Count5/5

    With 10 tools, the set is well within the typical 3–15 range and each tool earns its place by covering a distinct aspect of the language analysis domain. The count feels comprehensive without being bloated; no tool appears redundant.

    Completeness4/5

    The tool set covers a broad range of analysis operations: diagnostics, symbols, types, effects, IR, actors, and context estimation. The main gaps are raw source access and cross-project symbol search, which are not provided, but the server's read-only analysis focus is otherwise well covered.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables people and AI agents to query local code repositories as graphs through stdio MCP tools for project listing, search, dependency tracing, impact analysis, bridge detection, node inspection, bounded code reading, and optional LSP definition/reference lookups.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Local code-graph engine for AI coding workflows: static analysis of Rust, Cangjie, ArkTS, TypeScript/JavaScript, C/C++, Python, and Shell projects into symbols, imports, call graphs, and quality gates, with pre-commit change review and impact analysis. Read-only by design — never executes build scripts or uploads code.
      6
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to analyze codebases through Tree-sitter (WASM) by exposing tools for AST and symbol inspection, structural queries, reference and dependency lookup, complexity and code-similarity analysis, and project registration with directory scanning. Ships alongside a web studio with a Monaco editor, AST explorer, and read-only SQLite console.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes three read-only tools—impact, explain, and report—so an agent can query a prebuilt local DuckDB graph of a codebase to find the transitive reverse-dependencies of a symbol or file, inspect a symbol's structural neighbourhood, and introspect the index itself. Runs over stdio or Streamable HTTP, always read-only, with no external service.
      61 PyPI
      MIT