Hirð
The server exposes read-only compiler intelligence for Hirð programs via MCP, enabling agents to inspect, analyze, and summarize code without writing or executing anything.
Type- and effect-check a
.hirdfile’s whole directory/program, returning all diagnostics including warnings.Outline a module’s declarations, imports, symbol kinds, signatures, docs, and approximate token costs.
Infer the type and effect row of an expression at a source location.
Look up top-level definitions by name, including imported or qualified names.
Explain a function’s effect row with per-effect descriptions.
Render a definition’s typed intermediate representation as JSON.
Describe an actor’s protocol: messages, state, init, handlers, and effect rows.
Emit the actor/effect graph reachable from an actor, including actors, supervisors, and tools.
Summarize a symbol within a token budget for LLM context, with omitted sections reported.
Estimate token costs for loading a file’s declarations by category.
Hirð

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 # optionalWith 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 |
| type- and effect-check; coded diagnostics |
| emit readable Erlang, compile it to |
| build, then execute |
| record one run of the built-in demo, replay it against variants of the program |
| the typed IR of every definition |
| actors, mailboxes, handler rows, supervisors, tools, function rows |
| 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_fleetRecord 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 # replayThe 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 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 bybd.
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-featuresBEAM-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
Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
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 toolscheck_fileCheck programARead-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 graphARead-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 protocolARead-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 rowARead-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 budgetARead-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 contextARead-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 typeARead-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 moduleARead-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 definitionARead-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 fragmentARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Ask who calls a route, what a change breaks or who reads a field, across a system's repos.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Stateless TS/JS compiler facts for agents: references, imports, impact. No repo index or OAuth.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseAqualityBmaintenanceLocal 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.61MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceExposes 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 PyPIMIT