Installation

gem install elelem elelem-builtins

That gives you the elelem command, the agent loop, and the default tools and commands. You still need a provider to talk to a real model; see the quickstart.

Requirements #

Ruby 4.0 or newer. The gemspec sets required_ruby_version = ">= 4.0.0" and required_rubygems_version = ">= 4.0.0". Ruby 3.x will refuse to install it.
bash. elelem-builtins runs the execute tool through bash -c, and tab completion of file names uses compgen.

Optional, used by elelem-builtins when present:

glow renders the model’s Markdown replies. Without it, replies print as plain text.
bat shows files after read and write. Without it, elelem prints the content or the path.
diff shows a colored diff before write overwrites an existing file, when stdin is a terminal.

The gems #

Gem	What it adds
`elelem`	The core: agent loop, REPL, plugin loader, toolbox, and the `stub` provider. No tools.
`elelem-builtins`	Tools `read`, `write`, `execute`; commands `/exit`, `/clear`, `/help`, `/context`, `/tools`, `/provider`, `/reload`; a terminal renderer.
A provider gem	A model. For example `elelem-anthropic`, `elelem-openai`, `elelem-ollama`, or `elelem-llama`.

elelem-builtins is optional but you almost always want it. The elelem executable requires it if it is installed and carries on without it if it is not.

The full list of plugins is on the plugins page.

Check the install #

elelem --help

Usage: elelem [command] [options] [args]

Commands:
  chat              Interactive REPL (default)
  ask <prompt>      One-shot query (reads stdin if piped)
  files             Output files as XML (no options)
  help              Show this help

Options:
    -p, --provider NAME              Provider to use (default: stub)
        --model NAME                 Model to use, passed to the provider
        --system-prompt TEXT         Role text prepended to the system prompt
    -h, --help                       Show this help

If --model and --system-prompt are missing from that list, you have elelem 0.12.0 or older. Both options are new in 0.13.0.

There is no --version flag. elelem chat prints the version as its first line:

elelem v0.13.0

Press Ctrl-D to leave the REPL.

With no provider: the stub #

With no -p option, elelem uses the stub provider. It is built into core so a fresh install runs end to end without a model, an API key, or a network call.

The stub does not read your prompt. On every request it:

Emits the thinking text considering the request.
If the last message is a tool result, says done. and stops.
Otherwise says let me check. and calls the first tool in the toolbox with empty arguments.

So elelem ask hello exercises the whole loop: a reply, a tool call, a tool result, and a final reply. With elelem-builtins installed, the first tool is read, and the call fails schema validation because path is missing. That is expected. The loop still finishes with done.

If you see the stub’s replies when you expected a real model, you forgot -p.

Next #

Pick a provider and follow the quickstart.