Guides

Your first session

Install elelem with the default tools and Ollama, chat with a local model, and ask a one-shot question.

Beginner 10 minutes, plus the model download elelemelelem-builtinselelem-ollama

At the end of this guide you will have elelem installed, a chat session running against a model served by Ollama, and a one-line command that answers a question without opening a chat.

Before you start #

  • Ruby 4.0 or newer. Every elelem gem requires it.
  • Ollama installed and running on localhost:11434.
  • A project directory to try it in. elelem works on the directory you start it from.

1. Install the gems #

gem install elelem elelem-builtins elelem-ollama

Three gems, three jobs:

  • elelem is the harness: the agent loop, the REPL, and the plugin system. On its own it has no tools and only a stub provider that answers “done.”
  • elelem-builtins adds the tools read, write, and execute, the commands /help, /tools, /context, /clear, /provider, /reload, and /exit, and the terminal output. The elelem executable loads it automatically when it is installed.
  • elelem-ollama is a provider: it connects elelem to a model served by Ollama.

2. Pull a model #

elelem-ollama uses gpt-oss:latest unless you say otherwise.

ollama pull gpt-oss

To use another model, set OLLAMA_MODEL or pass --model on each run. If Ollama is not on localhost:11434, set OLLAMA_HOST.

3. Start a chat #

Run this from your project directory:

elelem chat -p ollama

-p picks the provider. Without it, elelem uses the stub provider, which is only there so a bare install runs. elelem-ollama also installs an elelem-ollama executable that defaults to Ollama, so elelem-ollama chat does the same thing.

You get a version line and a > prompt:

elelem v0.13.0
>

Ask for something that needs the files in front of you:

> what does this project do? read the README first.

The agent prints dots while it waits for the model, dim italic text while the model is thinking, and one line per tool call:

+ read({"path" => "README.md"})

Then the reply. If glow is installed, replies are rendered as Markdown through it; if bat is installed, files the agent reads are shown through it. Both are optional.

Note: elelem-builtins has no permission prompts. When the model calls execute, the command runs. Start in a directory you are willing to let it change, or install elelem-tools, whose confirm plugin asks before running tools marked ask.

4. Use a slash command #

Lines that start with / are commands, handled by elelem, not sent to the model. Press Tab after / to complete command names.

> /tools
| Tool | Description |
|------|-------------|
| read | Read file |
| write | Write file |
| execute | Run shell command (supports pipes and redirections) |

Now look at what the model has seen so far:

> /context

Each line is one message: the system prompt, your prompt, and the reply. /context 2 prints message 2 in full, and /context json dumps them all. /clear empties the history so the next prompt starts fresh. /help lists every command.

Leave with /exit or Ctrl-D. Every session is also written to a transcript under ~/.local/state/elelem/sessions/ (or $XDG_STATE_HOME/elelem/sessions/).

5. Ask a one-shot question #

ask runs a single turn and exits. Tools still work.

elelem ask -p ollama "which files in this directory are Ruby?"

Pipe text in and elelem appends it to the prompt inside a code fence:

git log --oneline -10 | elelem ask -p ollama "summarize what changed this week"

Use elelem in shell pipelines covers ask in scripts, including what goes to stdout and stderr.

6. Give it house rules (optional) #

elelem builds its system prompt from a one-line template plus two optional files: ~/.agents/AGENTS.md for rules you want everywhere, and the nearest AGENTS.md found walking up from the current directory for the project.

printf '# Rules\n\n- Run the tests with bin/test before saying you are done.\n' > AGENTS.md

The next session picks it up. Check with /context 1.

What you built #

A working install: the harness, three tools, a set of slash commands, and a local model behind Ollama. You ran an interactive session and a one-shot query, and you know where to put project rules.

Next steps #