Context

Context is everything the model sees besides your prompt: the system prompt, your project’s instructions, and the conversation so far. elelem keeps it small and rebuilds the system prompt on every request.

The system prompt #

The default template is two lines of ERB:

You are a terminal coding agent.

<%= agents_md %>

agents_md is the content of your AGENTS.md files, described below, or nothing if there are none.

The template is rendered on every request to the provider, not once per session. Edit AGENTS.md mid-session and the next request sees the change.

Role text: --system-prompt #

elelem chat -p anthropic --system-prompt "You review Ruby code. Report bugs only."

The text goes in front of the rendered template, separated by a blank line. It is used as-is, never rendered as ERB.

Replacing the template #

From Ruby, pass template: to replace the default template entirely:

Elelem.ask("Summarize the README", provider: "anthropic",
           template: "You are a terse technical writer.\n\n<%= agents_md %>")

A template is ERB with trim_mode: "-". It can call agents_md. The CLI has no option for this; elelem-tools uses it for the sub-agents behind task and /init.

See it #

With elelem-builtins, /context lists every message the model would see, numbered, with the system prompt first. /context 1 prints the full system prompt. /context json dumps all messages as JSON.

AGENTS.md #

elelem reads two AGENTS.md files:

1. Global: ~/.agents/AGENTS.md. Your own rules, for every project.
2. Project: the first AGENTS.md found walking up from the current directory to /. Only the nearest one is used.

Both are included, global first, separated by a blank line. Either can be missing.

AGENTS.md is a shared convention, so the same file serves other agents. Put in it what you would tell a new engineer: how to build, how to test, conventions, and what not to touch. elelem-tools adds /init, which asks the model to write one for the current project.

The conversation #

The conversation holds your prompts and the model’s final replies. Tool calls and tool results are sent to the model during a turn but are not kept afterward. See How it works.

With elelem-builtins, /clear empties the conversation. With elelem-tools, /compact replaces it with a summary written by the model.

The .agents directory #

elelem and its plugins share one layout. Most paths exist twice: under your home directory for everything you run, and under the project for that project only. Where both are read, the home copy is read first and the project’s copy second, so the project’s settings take precedence.

~/.agents/
├── AGENTS.md            global instructions          core
├── plugins/*.rb         plugin files                 core
├── models/*.gguf        local model files            elelem-llama, elelem-ggml
├── skills/NAME/SKILL.md skills                       elelem-skills
├── remote-skills/       skills fetched with /skills  elelem-skills
├── mcp.json             MCP servers                  elelem-mcp
└── permissions.json     tool permissions             elelem-tools

PROJECT/
├── AGENTS.md            project instructions         core
└── .agents/
    ├── plugins/*.rb     project plugin files         core
    ├── skills/NAME/SKILL.md                          elelem-skills
    ├── mcp.json                                      elelem-mcp
    └── permissions.json                              elelem-tools

plugins/ #

Ruby files that call Elelem.configure. Loaded from ~/.agents/plugins/ first, then .agents/plugins/ in the current directory. See Plugins.

models/ #

Used by elelem-llama and elelem-ggml when no model is given with --model (llama only) or ELELEM_GGUF_MODEL. They pick:

1. ~/.agents/models/default.gguf, which can be a symlink, if it exists.
2. Otherwise the only *.gguf file in the directory.
3. Otherwise they stop with an error asking you to set ELELEM_GGUF_MODEL or create the default.gguf symlink.

There is no project-level models/.

skills/ #

Used by elelem-skills. Each skill is a directory holding a SKILL.md with name and description in its YAML front matter. Skills are read from ~/.agents/remote-skills/ (installed by /skills fetch), then ~/.agents/skills/, then .agents/skills/. A later skill with the same name replaces an earlier one, so the project wins.

mcp.json #

Used by elelem-mcp. The mcpServers objects from ~/.agents/mcp.json and .agents/mcp.json are merged, the project’s entries replacing global ones with the same name. Values written as ${VAR} in a server’s env or headers are filled from the environment.

permissions.json #

Used by the confirmation hook in elelem-tools. A JSON object of tool name to allow, deny, or ask. The gem ships defaults (read and write allowed, execute ask), then applies ~/.agents/permissions.json, then .agents/permissions.json. A tool with no entry is ask. When elelem cannot prompt, as in elelem ask, ask allows the call.

Files outside .agents #

Two plugins write elsewhere:

• elelem-builtins appends everything its terminal output prints to $XDG_STATE_HOME/elelem/sessions/TIMESTAMP-PID.transcript, or ~/.local/state/elelem/sessions/ when XDG_STATE_HOME is not set. One file per session.
• elelem-mcp stores OAuth tokens in ~/.config/elelem/tokens/.