Documentation menu

Start

Introduction

What elelem is, what it is not, and the principles behind it.

Fast, correct, autonomous. Pick two.

Every coding agent trades between speed, correctness, and how much it does on its own. elelem gives you the loop and lets you decide the trade: which model, which tools, which checks before a tool runs.

What elelem is #

A coding agent harness written in Ruby. It runs in your terminal, sends your prompt to a model, runs the tools the model asks for, and feeds the results back until the model stops asking.

The core gem, elelem, holds the agent loop, the REPL, the plugin loader, and a toolbox with JSON Schema validation. It is under 1,000 lines. It ships with one provider, stub, which talks to no model at all, and no tools.

Everything else is a plugin:

  • Providers connect a model: elelem-anthropic, elelem-openai, elelem-ollama, or elelem-llama, which runs a GGUF file inside the elelem process.
  • Tools are functions the model can call. elelem-builtins adds read, write, and execute. elelem-tools adds more.
  • Commands are slash commands you type: /help, /context, /reload.

A plugin is any Ruby file or gem that calls Elelem.configure. Drop a .rb file in .agents/plugins/ and it loads on the next start.

What elelem is not #

  • Not a framework. There is no base class to inherit and no DSL beyond Elelem.configure. A tool is a name, a description, a JSON Schema, and a block.
  • Not configured by files. elelem itself reads no config file. Behavior changes through plugins, command-line options, and environment variables. A few plugins read their own files, such as elelem-mcp reading .agents/mcp.json.
  • Not a sandbox. Tools run with your permissions. elelem-builtins executes shell commands without asking. Add elelem-tools for a confirmation prompt, or write a before hook that refuses what you do not want.
  • Not an IDE. It is a REPL in your terminal and a one-shot ask command for scripts.

Design principles #

These come from the core README.

  • Unix philosophy. Simple, composable, minimal. elelem ask reads from a pipe and writes to stdout, so it fits in a shell pipeline.
  • Convention over configuration. Plugins live in .agents/plugins/. Project instructions live in AGENTS.md. Models live in ~/.agents/models/.
  • No defensive code beyond what is necessary. Errors are caught at a few boundaries (provider calls, tool calls, slash commands, plugin loading) and reported. Nothing else is wrapped.
  • Trust the model. elelem assumes a capable model that behaves like a responsible engineer. It does not second-guess tool calls unless a plugin asks it to.

Next #

Install elelem, then follow the quickstart.