# elelem

> elelem is a minimal, pluggable coding agent for the terminal, written in Ruby and MIT licensed. Its core is small enough to read in an afternoon; models, tools, and interfaces are plugins. It aims to be the Vim of coding agents: a small core you shape with plugins kept in your own dotfiles and repositories.

Key facts:

- Install: `gem install elelem elelem-builtins elelem-ollama`, then `elelem chat -p ollama`. Requires Ruby 4.0 or later.
- Providers: Claude (Anthropic API), Ollama, and GGUF models loaded in-process with llama.cpp (no server, no network call). Choose one with `-p NAME`.
- Plugins: a plugin is any Ruby file that calls `Elelem.configure`. elelem loads every file in `~/.agents/plugins/`, then `.agents/plugins/` in the current project. Providers are plugins too.
- Design: the core is closed for modification and open for extension (the open/closed principle).
- Unix: `elelem ask` reads a pipe and writes the reply to stdout, e.g. `git diff | elelem ask -p ollama "write a commit message"`.
- Maturity labels: ready (works today), alpha (works with known gaps), lab (experiments in how inference works).
- Known issues are public: https://github.com/elelem-sh/elelem.sh/issues
- Source: https://src.mokhan.ca/elelem/ (clone from https://git.mokhan.ca/elelem/NAME.git). Patches by email.
- Built by mo khan (https://www.mokhan.ca/) through 2809074 Alberta Ltd., a self-funded company incorporated in Alberta, Canada. The maintainer is available for paid work on elelem and on identity libraries such as saml-kit and scim-kit: https://elelem.sh/hire/
- Contact: hello@elelem.sh

## Docs

- [Introduction](https://elelem.sh/docs/introduction/index.md): What elelem is, what it is not, and the principles behind it.
- [Installation](https://elelem.sh/docs/installation/index.md): Install Ruby 4.0, the elelem gem, and the default tools, then check that it runs.
- [Quickstart](https://elelem.sh/docs/quickstart/index.md): Install a provider, start a chat, and run a one-shot question from the shell.
- [How it works](https://elelem.sh/docs/how-it-works/index.md): The agent loop step by step, the objects behind it, and the path a single tool call takes.
- [Providers](https://elelem.sh/docs/providers/index.md): The one method a provider implements, the messages and events it handles, and how -p NAME finds it.
- [Tools and commands](https://elelem.sh/docs/tools-and-commands/index.md): Add tools the model can call, guard them with hooks, and add slash commands you can type.
- [Plugins](https://elelem.sh/docs/plugins/index.md): What a plugin is, where elelem loads plugins from and in what order, and how to reload them.
- [Context](https://elelem.sh/docs/context/index.md): How the system prompt is built, where AGENTS.md is read from, and what lives in the .agents directory.
- [CLI](https://elelem.sh/docs/cli/index.md): Every elelem command and option, with examples for chat, one-shot questions, pipes, and file bundles.
- [Plugin API](https://elelem.sh/docs/plugin-api/index.md): Every public method a plugin author touches, with signatures, defaults, and short examples.
- [Environment variables](https://elelem.sh/docs/environment/index.md): Every environment variable read by elelem core and its plugins, with defaults.
- [Changelog](https://elelem.sh/docs/changelog/index.md): Where to find the release history of elelem and every plugin gem.

## Guides

- [Your first session](https://elelem.sh/guides/first-session/index.md): Install elelem with the default tools and Ollama, chat with a local model, and ask a one-shot question.
- [Run elelem fully offline](https://elelem.sh/guides/local-models/index.md): Run a GGUF model inside the elelem process with elelem-llama, with GPU offload and a context size you choose.
- [Write a tool plugin](https://elelem.sh/guides/write-a-tool/index.md): Add a tool the model can call, in one Ruby file, then package it as a gem.
- [Write a provider plugin](https://elelem.sh/guides/write-a-provider/index.md): Connect elelem to a new model API by implementing one method, fetch, that streams events back to the agent.
- [Connect MCP servers](https://elelem.sh/guides/mcp-servers/index.md): Give the agent the tools of any MCP server, local over stdio or remote over HTTP with OAuth, using elelem-mcp.
- [Use agent skills](https://elelem.sh/guides/agent-skills/index.md): Write a SKILL.md file, let the model load it when it needs it, and install skills from a remote index.
- [Use elelem in shell pipelines](https://elelem.sh/guides/scripting/index.md): Pipe text into elelem ask, feed it files with elelem files, and use the reply in scripts and git workflows.
- [Compare models with elelem-evals](https://elelem.sh/guides/evals/index.md): Run the same coding tasks against different providers and models, and write your own cases to test what matters to you.

## Plugins

- [elelem](https://elelem.sh/plugins/elelem/index.md): The agent loop. Nothing else. The core gem: the agent loop, the plugin registry, and the elelem command. Tools, slash commands, and model providers all come from plugins. Maturity: ready. Install: `gem install elelem`.
- [elelem-builtins](https://elelem.sh/plugins/builtins/index.md): Read, write, run. The default tools and slash commands: read and write files, run shell commands, and manage the session. Loaded automatically by the elelem command when installed. Maturity: ready. Install: `gem install elelem-builtins`.
- [elelem-tools](https://elelem.sh/plugins/tools/index.md): More tools. Permission prompts. Adds search, edit, git, sub-agent, and verification tools, three slash commands, and a permissions hook that asks before a tool runs. Maturity: ready. Install: `gem install elelem-tools`.
- [elelem-anthropic](https://elelem.sh/plugins/anthropic/index.md): Claude, through the Anthropic API. Connects elelem to Claude through the Anthropic Messages API, or through Google Cloud Vertex AI. One gem, two providers. Maturity: ready. Install: `gem install elelem-anthropic`.
- [elelem-openai](https://elelem.sh/plugins/openai/index.md): OpenAI chat completions. Connects elelem to OpenAI models through the Chat Completions API, with streaming and tool calls. Maturity: alpha. Install: `gem install elelem-openai`.
- [elelem-ollama](https://elelem.sh/plugins/ollama/index.md): Local models through Ollama. Connects elelem to a running Ollama server through its native /api/chat endpoint, with streaming, tool calls, and thinking output. Maturity: ready. Install: `gem install elelem-ollama`.
- [elelem-llama](https://elelem.sh/plugins/llama/index.md): llama.cpp, in-process. Runs GGUF models inside the elelem process through llama.cpp. No server, no network call. Maturity: ready. Install: `gem install elelem-llama`.
- [elelem-mcp](https://elelem.sh/plugins/mcp/index.md): MCP servers as tools. Connects elelem to Model Context Protocol servers over stdio or HTTP and adds every tool they list to the agent. Handles OAuth for HTTP servers that ask for it. Maturity: ready. Install: `gem install elelem-mcp`.
- [elelem-skills](https://elelem.sh/plugins/skills/index.md): Agent skills, on demand. Loads SKILL.md files from .agents/skills and exposes them to the agent through a skill tool and a /skills command. Can install skills published by a website. Maturity: ready. Install: `gem install elelem-skills`.
- [elelem-server](https://elelem.sh/plugins/server/index.md): elelem in a browser tab. Serves a chat page and runs an elelem session behind it, so you can drive the agent from a browser or a phone. It has no authentication and listens on every network interface. Maturity: alpha. Install: `gem install elelem-server`.
- [elelem-ratatui](https://elelem.sh/plugins/ratatui/index.md): A Rust terminal UI. Replaces elelem's line-based terminal with a full-screen ratatui interface, drawn by a small Rust binary that talks to Ruby over JSON lines. Early, and not published to RubyGems. Maturity: alpha. Source only.
- [elelem-evals](https://elelem.sh/plugins/evals/index.md): Test the agent, not the model. Runs scripted coding tasks against any elelem provider in throwaway directories and checks the results with shell commands, file contents, and the final reply. Not published to RubyGems. Maturity: alpha. Source only.

## Company
- [Why elelem](https://elelem.sh/why/index.md): The manifesto: pick two, small is a feature, the Vim of coding agents, open for extension.
- [Company](https://elelem.sh/company/index.md): Who builds elelem, what works today, the roadmap, and how to work together.
- [Hire the maintainer](https://elelem.sh/hire/index.md): Paid feature work, plugins, integrations, and identity (SAML, SCIM, OIDC) engineering.

## Optional

- [elelem-ggml](https://elelem.sh/plugins/ggml/index.md): A transformer you can read. A Qwen2 forward pass built by hand on ggml, with the tokenizer in Ruby. 466 lines of C and about 300 lines of Ruby from prompt to tensor ops. Maturity: lab. Source only.
- [elelem-llama2](https://elelem.sh/plugins/llama2/index.md): llama2.c, wired into elelem. Runs Andrej Karpathy's llama2.c inside elelem. One C file does the whole forward pass; a 161-line C++ shim streams tokens back to Ruby. Maturity: lab. Source only.
- [elelem-candle](https://elelem.sh/plugins/candle/index.md): Rust in-process. Inference not yet. A skeleton provider that calls Rust from Ruby through rb_sys and magnus. The FFI and token streaming work; the model is a stub that echoes your prompt. Maturity: lab. Source only.
- [elelem-diffusion](https://elelem.sh/plugins/diffusion/index.md): Images from the agent, locally. Adds image, video, and upscale tools backed by stable-diffusion.cpp, compiled into the elelem process and called through Fiddle. Maturity: lab. Source only.
- [Manual](https://elelem.sh/man/index.md): Short reference pages for elelem(1) and every plugin.
- [Full documentation in one file](https://elelem.sh/llms-full.txt)