# 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 token (in your shell or `.env`):

- `EUE_PROVIDER` — LLM provider. Default `openrouter`.
- `EUE_AI_TOKEN` — **Required.** API token for the chosen provider.
- `EUE_MODEL` — 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_AI_TOKEN=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=bot_token eue telegram
```

Or pass token/workspace via options:

```bash
eue telegram --token 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_AI_TOKEN` | — | **Required.** API token 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_EXECUTE_TIMEOUT_MS` | `30000` | Timeout for execute 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`. |
| **Execute** | | |
| `EUE_EXECUTE_SHELL` | `$SHELL` or `/bin/sh` | Command runner executable for `,execute` tool. |
| **Telegram** | | |
| `EUE_TELEGRAM_TOKEN` | — | **Required for Telegram.** Bot token. |
| `EUE_TELEGRAM_ALLOW_CHATS` | — | Empty = all chats; non-empty = only these chat_id (use strict allowlist in production). |
| `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).
>
> 朴素编程 can be summed up as: open the editor, type code, run code. The opposite is Vibe Coding: tell your requirements to an AI coding agent; the AI writes the code, runs it, and debugs it.
>
> — TJ (Thaddeus Jiang)