# Context

> How the system prompt is built, where AGENTS.md is read from, and what lives in the .agents directory.


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:

```text
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`

```bash
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:

```ruby
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](https://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](/docs/how-it-works/#what-the-conversation-keeps).

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.

```text
~/.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](/docs/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/`.


Canonical: https://elelem.sh/docs/context/