# EUE

EUE is a self-evolving AI agent. It runs as a CLI conversational agent and a Telegram autonomous agent, with workspace isolation, strict command boundaries, and dynamic skill loading. EUE does not expose HTTP, does not require a database, and runs locally and deterministically.

# Installation

```bash
mix escript.install hex eue
```

If you installed an older escript build, reinstall with `--force`:

```bash
mix escript.install hex eue --force
```

# Before running

Set at least the LLM provider, model, and API key (e.g. in your shell or a `.env` file):

- `EUE_API_KEY` — **Required.** API key for your chosen provider.
- `EUE_PROVIDER` — Optional, default `openrouter`. LLM provider.
- `EUE_MODEL` — Optional if the provider has a default. Model id (e.g. `openai/gpt-4o`, `z-ai/glm-5`).

Example:

```bash
export EUE_PROVIDER=openrouter
export EUE_MODEL=openai/gpt-4o
export EUE_API_KEY=sk-...
```

# Running

**CLI**

```bash
eue
```

Workspace defaults to the current directory. To use another directory: `eue --workspace /path/to/workspace`.

**Telegram**

```bash
EUE_TELEGRAM_TOKEN=your_bot_token eue telegram
```

Or pass token/workspace directly:

```bash
eue telegram --token your_bot_token --workspace /path/to/workspace
```

# Configuration

All parameters are environment variables. Set them in your shell or a `.env` file.

| Variable | Default | Description |
|----------|---------|-------------|
| **Provider & model** | | |
| `EUE_PROVIDER` | `openrouter` | LLM provider (e.g. openrouter). |
| `EUE_API_KEY` | — | **Required.** API key for the provider. |
| `EUE_MODEL` | provider default | Model id (e.g. `openai/gpt-5.2-chat`, `z-ai/glm-5`). |
| `EUE_FALLBACK_MODEL` | provider default | Fallback model when primary is unavailable. |
| **Loop & limits** | | |
| `EUE_MAX_STEPS` | `20` | Max agent loop steps per run (positive integer). |
| `EUE_HISTORY_MESSAGES` | `40` | Max history messages sent to the model. |
| `EUE_REQUEST_TIMEOUT_MS` | `60000` | CLI request timeout in milliseconds. |
| `EUE_BASH_TIMEOUT_MS` | `30000` | Timeout for bash/shell tool in milliseconds. |
| **Workspace & paths** | | |
| `EUE_WORKSPACE_PATH` | cwd (CLI) / unset | Workspace root (Telegram/CLI). |
| `EUE_WORKSPACE_ROOT` | — | Backward-compatible alias for `EUE_WORKSPACE_PATH`. |
| **Shell** | | |
| `EUE_SHELL` | `$SHELL` or `/bin/sh` | Shell executable for `,bash` and bash tool. |
| `EUE_SHELL_MODE` | `login` | Shell mode: `login` (-lc), `interactive` (-ic), `interactive_login` (-lic). |
| **Telegram** | | |
| `EUE_TELEGRAM_TOKEN` | — | **Required for Telegram.** Bot token. |
| `EUE_TELEGRAM_ALLOW_CHATS` | — | Chat allowlist (JSON array or comma-separated ids). |
| `EUE_TELEGRAM_ALLOW_FROM` | — | **Required for Telegram.** Sender allowlist (ids/usernames). Empty = deny all. |
| `EUE_TELEGRAM_SHOW_STEPS` | `true` | Show step progress lines in Telegram; `false`/`0`/`no`/`off` to hide. |
| **Behavior** | | |
| `EUE_AUTORUN_PREFLIGHT` | `false` | If `true`, auto run `pwd` and `ls` for directory/project questions. |
| `EUE_ALLOWED_SKILLS` | — | Restrict to given skills (comma-separated); unset = all allowed. |
| **Output & logging** | | |
| `EUE_PROGRESS_STYLE` | `verbose` | Progress style: `verbose` or `compact` (summary only). |

If your configured model is not found, EUE retries with a fallback model (set `EUE_FALLBACK_MODEL`; when `EUE_PROVIDER=openrouter` the default is `openrouter:openai/gpt-5.2-chat`).

# Workspace and commands

Each workspace keeps its own state under `<workspace>/.EUE/` (skills, tapes, sessions, artifacts, logs). Only lines beginning with `,` execute; use `,help` for commands.

For building from source and contributor workflows, see [Development](docs/en/Development/README.md).

# Acknowledgments

EUE was inspired by [Bub](https://github.com/PsiACE/bub) — a project that showed me the beauty of minimal, focused tooling.

Bub's philosophy of "no forced preflight" directly influenced EUE's approach to agent autonomy.

> This may be my last project of "朴素编程" (Naive Programming).
>
> 朴素编程 means: writing code with pure intention, minimal abstraction, direct expression — close to the problem, close to the human.
>
> — TJ (Thaddeus Jiang)