Skip to main content

Ethos

Personalities aren't hats you swap in the prompt. They're enforced boundaries. A personality in Ethos is a directory of files — SOUL.md, config.yaml, toolset.yaml — that the runtime treats as a structural component. Switching it changes prompt, tools, memory, and model atomically. The boundary is enforced at the tool registry, not requested in the prompt.

That single decision pays off six ways:

  • Structural isolation. The reviewer personality's toolset.yaml omits write_file. No prompt — yours, the model's, an injected one — can talk it into editing the diff under review. The framework refuses the call.
  • One agent, every surface. Nine surfaces — CLI, web dashboard, desktop app, VS Code extension, and five channel adapters (Telegram, Discord, Slack, WhatsApp, email) — share the same session layer. Start a conversation on Telegram, continue it on the CLI, switch personalities mid-thread — same memory, same history.
  • Safe plugins. Every tool declares what it reads, what it writes, and what network it touches. The runtime enforces those declarations per call. Granting an unfamiliar plugin to a personality is bounded by what its toolset already allows.
  • Teams, not just agents. A coordinator personality decomposes one request into specialist tasks; the team executes them against a durable kanban board with a full audit trail. Same primitives — personality, toolset, session — composed.
  • A web dashboard and desktop app. ethos serve --web launches a React SPA. Chat, sessions, personalities, skills, MCP servers, plugins, memory, teams, cron jobs, activity feed, batch/eval — managed from one place. The Electron desktop app adds a system tray, quick-chat overlay, and global shortcuts.
  • Skills that evolve. The skill-evolver analyzes eval output, proposes rewrites for underperforming skills, and drafts new skills for recurring patterns. You approve or reject from the web dashboard or desktop app.

Three personalities ship by default for everyday use. Two system personalities — personality-architect and team-architect — are available for building and managing agents. Plugins register slash commands (e.g. /market brief) that work across CLI, Telegram, Discord, Slack, and the web UI. Your existing Claude Code, OpenClaw, OpenCode, and Hermes skill libraries run as-is, filtered to the right specialist per personality. Zero mode (ethos -z) runs one-shot prompts with no readline — pipe it into scripts, CI, or cron. Inline @ref context (@file, @url) pulls external sources into the conversation without copy-paste.

The runtime streams end-to-end: every turn emits an AsyncGenerator<AgentEvent> — text deltas, tool events, usage, done — and every component is injected at construction, never reached for globally.

What you can build​

Ship a Telegram bot that remembers you

Pick a personality, connect a Telegram token, deploy. Sessions persist across restarts; memory carries forward.

Build dashboards from plugin data

Plugins expose SQLite databases and declare widget templates. You compose draggable panels that query those data sources in real time.

Run one-shot prompts in CI pipelines

ethos -z "summarize this diff" — zero mode, no readline, stdout-only. Pipe it into git hooks, GitHub Actions, cron.

Let the agent learn from usage

The skill-evolver watches eval results, proposes rewrites for weak skills, drafts new ones for recurring patterns. You approve from the dashboard.

Manage everything from one dashboard

Web dashboard or desktop app. Chat, sessions, personalities, plugins, MCP servers, memory, teams, mesh topology, cron, batch/eval — one surface.

Extend with slash commands

Plugins register commands like /market brief that work across CLI, Telegram, Discord, Slack, and the web UI.

Two doors​

The rest of these docs split by what you're here to do — run Ethos, or extend it.

Using Ethos →

Install the CLI, configure a provider, run your first chat, ship a Telegram bot. Five minutes to first message.

Building on Ethos →

Write a tool, add an LLM provider, build a channel adapter, publish a plugin. Ten minutes to first commit.

Before you choose a door​

  • What is Ethos? — 90-second mental model of personalities, sessions, and the streaming event contract.
  • Architecture in 90 seconds — one diagram of AgentLoop and every component that hangs off it.
  • Why Ethos? — honest comparison to LangChain, CrewAI, AutoGen, OpenClaw, and Hermes.
  • Glossary — every domain term in one place.

For AI agents reading these docs​

Other AI agents (Claude Code, Cursor, OpenClaw, Hermes) are first-class readers of Ethos's docs. Once Phase 6 of the docs rewrite lands, three agent-readable surfaces ship alongside the site: llms.txt (link-index), llms-full.txt (full content), and per-page raw markdown at <path>.md. The convention is documented in the /docs skill, §Agent-readable surface.

The full Ethos type contract — AgentEvent, Tool, LLMProvider, MemoryProvider, HookRegistry, SessionStore — lives in a single zero-dependency package (@ethosagent/types). Every extension point is typed there. When scaffolding an integration, start with those interfaces; all concrete implementations (the CLI, channel adapters, storage backends) are downstream of them.

If you are generating Ethos configuration (personalities, mcp.json, config.yaml), the schema files live under packages/types/src/ in the repository. The MCP config reference and personality config reference are the human-readable versions of those schemas.

Session keys follow the convention cli:<cwd-basename> at the CLI. Different working directories get independent conversation histories. The same session key used across Telegram, CLI, and a channel adapter returns the same message history — the session store is keyed by context, not by channel.

Tool calls outside a personality's toolset.yaml allowlist are rejected at the framework level and return an error tool_result to keep the LLM message contract intact — the rejection is never silently dropped.