Getting started

What you're setting up

Elfie treats a language model as a compiler. You write definitions: what each piece of your program is, what it must do, and how to test it. A compiler agent writes code in your target language that satisfies them, and a second agent checks that it did.

The elfie command handles everything that must be exact. It parses and checks your definitions, plans what needs to be built, hands each piece to the compiler, accepts the result, and records what was built from what. It does not contain a model. You choose the agent that writes code and name it in your project's configuration.

Install the CLI

1. 1

   Download a release

   Download the elfie binary for your platform from the releases page. Builds are published for Linux, macOS, and Windows.

2. 2

   Put it on your PATH

   Move the binary into a directory on your PATH, such as ~/.local/bin or /usr/local/bin.

3. 3

   Check that it runs

   Terminal

   elfie version

   Output

   elfie 0.1.0

Create a project

Run elfie init in an empty directory. Give it a name, or leave the name out to use the directory's name.

Terminal

mkdir hello && cd hello
elfie init hello

Output

created /home/you/hello/elfie.json

init creates these files:

Connect a compiler

elfie compile runs the command that elfie.json names under compiler, once for each batch of work, with the request on standard input. The command can be any agent that can read that request, edit files, and run commands. A second command, under verifier, reviews the result.

elfie.json

{
  "name": "hello",
  "compiler": "scripts/compile.sh",
  "verifier": "scripts/verify.sh"
}

Here is a minimal compiler script that uses Claude Code:

scripts/compile.sh

#!/usr/bin/env bash
# Run by elfie compile once per batch, with the request on standard input.
set -e
exec claude -p \
  --permission-mode acceptEdits \
  --mcp-config .mcp.json \
  --append-system-prompt "$(cat scripts/compiler-prompt.md)"

Starter compiler and verifier scripts, with the prompts that go with them, are in the Elfie repository. Copy them into scripts/ and adjust them to your agent.

The Configuration page lists the environment variables the compiler receives. Compiler details describes what the request contains and what the compiler must do with it.

Add packages

Targets, frameworks, and platforms come from packages. A package is a directory of .lfy files, and you list it in elfie.json under dependencies with the path to its root.

elfie.json

{
  "name": "hello",
  "compiler": "scripts/compile.sh",
  "verifier": "scripts/verify.sh",
  "dependencies": {
    "cli": { "root": "vendor/cli" },
    "platforms": { "root": "vendor/platforms" },
    "python": { "root": "vendor/python" }
  }
}

Packages are available for TypeScript, Python, Rust, Bun, Node.js, npm, React, Next.js, HTTP, command lines, and platforms. Put the ones you need in vendor/, and list each one in elfie.json. The standard library, the package named elfie, is always loaded, so you never list it.

Set up your editor and agents

elfie lsp is a language server. Editors that speak the Language Server Protocol get diagnostics, hover, go to definition, symbols, completion, semantic highlighting, and formatting. A Visual Studio Code extension lives in the repository under editors/vscode.

elfie mcp is an agent server: it gives agents tools to look up entities, references, problems, and generated code. Register it for Claude Code and other MCP clients in .mcp.json:

.mcp.json

{
  "mcpServers": {
    "elfie": { "command": "elfie", "args": ["mcp"] }
  }
}

Project layout

A project after its first compile

hello/
├── elfie.json          project manifest
├── def/                your definitions
├── vendor/             packages you depend on
├── elfie-compile/
│   ├── maps/           source maps, one file per unit
│   ├── reviews/        the verifier's verdicts
│   └── cache/          scratch space, ignored by git
├── elfie-requests/     compile log, and files for blocked work and questions
└── out/                generated code, wherever your target puts it

Next

Your first program

Write a small command-line program, compile it, and change it.

Start building →

Language guide

Familiar concepts

Skim the parts of Elfie that work like the languages you already know.

Read the language guide →