convez.ai
MCP ServerAutomaçãoIntermediário
ethosagent

Ethos — Framework de Agentes IA com Identidade

ethosagent/ethos

Agentes IA especialistas com arquitetura de personalidade, não prompts

Ver no GitHub
BomPluginScore · de 0 a 100

Framework TypeScript que cria agentes IA especialistas com identidades bem definidas, não chatbots genéricos. Vem com 5 personalidades padrão (engenheiro, pesquisador, revisor, coach, operador) que rodam em CLI, Telegram, Discord, Slack e Email, mantendo coerência de voz e memória.

Instalação

$npx convez-ai ethosagent/ethos

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
23
Forks
1
Acompanhando
0
Saúde
75%
Último commit
há 2 dias
Versão
v0.9.0
Issues abertas
4
Contribuidores
2

Casos de uso

  • Criar equipes de agentes com papéis definidos e identidades distintas
  • Executar tarefas técnicas (escrita de código, revisão, pesquisa) com especialistas IA
  • Coordenar agentes através de artefatos visíveis e trilhas de auditoria

Veredito

Ethos é uma alternativa séria a orquestradores de agentes genéricos, com foco em especialização e identidade arquitetural. Produção-ready com suporte multi-canal e bom para times que querem clareza de responsabilidades entre agentes.

README

A tradução para o português deste README ainda está na fila.

Ethos

CI npm License: MIT Node

Most AIs try to be good at everything. Ethos gives you a team — each one really good at just one thing.

Ethos builds AI agents that have an identity — not a prompt.

You wouldn't hire one person to be your engineer and your researcher. Why pretend an AI can? Build your own personality with Ethos.

Five ship by default — pick one, or build your own:

  • engineer — writes working code; tests what ships; refuses to pad.
  • researcher — finds primary sources; flags uncertainty; shows the reasoning.
  • reviewer — finds real problems; separates blocking from suggestion; does not soften.
  • coach — asks one question at a time; helps you think, not for you.
  • operator — dry-runs before destructive action; confirms; documents what happened.

Each runs across CLI, Telegram, Discord, Slack, and Email — same identity, same memory, same boundary, every surface. Teams are the other half: named personalities that coordinate through visible artifacts — a kanban board, a shared topic file, an audit trail — not behind one chatbot voice. The user can see who decided what.

Quick install

Standard install (Node 24+, Linux / macOS / WSL2)

npm i -g @ethosagent/cli
ethos setup           # provider + API key + personality selection (interactive)
ethos chat            # interactive REPL — talk to your agent

ethos setup writes ~/.ethos/config.yaml and stores credentials in ~/.ethos/secrets/<ref> with chmod 0600.

Production install (always-on box: VPS, mini PC, Raspberry Pi 4+, Mac mini)

npm i -g @ethosagent/cli pm2
ethos setup
curl -O https://ethosagent.ai/ecosystem.config.js
pm2 start ecosystem.config.js && pm2 save && pm2 startup

ethos run-all spawns the gateway (all configured bot adapters + cron) and the web dashboard under one supervisor. PM2 keeps it alive across reboots and restarts on crash. Sizing, log rotation, upgrade flow, and troubleshooting: Deploy in production →.

Windows note

Native Windows is not a primary target. Use WSL2 (Ubuntu 22.04 or 24.04). Node 24+ inside the WSL distro; ~/.ethos/ lives in the Linux home, not the Windows mount.

Installing the desktop app on macOS

Since the app is unsigned and unnotarized, macOS will block it on first open:

"Ethos" cannot be opened because Apple cannot verify it is free from malware.

Option A — right-click method (easier):

  1. Open the .dmg and drag Ethos to Applications
  2. Right-click Ethos.app in your Applications folder
  3. Click Open
  4. Click Open again in the dialog that appears
  5. The app opens. This only needs to be done once.

Option B — terminal (if Option A doesn't work on macOS 15+):

xattr -dr com.apple.quarantine /Applications/Ethos.app

Getting started

ethos setup                       # first-time config — provider, keys, default personality
ethos chat                        # interactive REPL against the default personality
ethos chat --personality engineer # one-off with a specific personality

ethos personality list            # five built-ins + anything you've added
ethos personality show engineer   # character sheet: identity, tools, skills, model, fs_reach
ethos personality create my-team  # scaffold ~/.ethos/personalities/my-team/

ethos gateway                     # run all configured bot adapters (Telegram + Slack + ...)
ethos run-all                     # supervisor: gateway + web dashboard, one command

ethos sessions list               # browse past conversations
ethos sessions show <id>          # full transcript + tool calls

ethos memory show                 # MEMORY.md + USER.md for the active personality
ethos memory add "We use ESM, never CJS"   # durable note — survives sessions

ethos secrets list                # which credentials are configured (refs only, never values)
ethos secrets set providers/anthropic/apiKey   # set or rotate — chmod 0600 enforced

ethos cron add daily-digest "0 8 * * *" "summarize what you learned yesterday"
ethos skills install steipete/slack   # any clawhub skill, no fork required
ethos claw migrate --dry-run      # one-step from an existing OpenClaw install

ethos doctor                      # boot-time sanity check — config, keys, perms, providers

Full subcommand reference: CLI reference →.

CLI vs chat surfaces

The same actions are available on every surface. Pick the one the conversation lives on; sessions and memory follow the personality, not the channel.

You want toOn the CLIIn Telegram / Slack / Discord / Email
Talk to the active personalityethos chatDM the bot, or @ethos-bot in a channel / group
Switch personality mid-conversation/personality reviewer/personality reviewer (if the bot's binding allows it)
Start a fresh session/new/new
See what the active personality is/personality/personality (or /ethos personality on Slack)
Inspect the full character sheetethos personality show <id>/ethos personality rich (Slack)
Check what tools/skills are loadedethos personality show <id>/ethos skills
Run a quick lookup against memoryethos memory show/ethos memory show
Append a durable noteethos memory add "..."/ethos memory add ...
List recent sessionsethos sessions list(CLI-only today)
Bring up the production stackethos run-all(operator-only command)

Bots are bound to a personality at config time. The default binding locks /personality switching off so external users can't reroute the bot — flip allowSlashSwitch: true if you want them to.

Documentation

PageWhat it covers
What is Ethos?The 90-second mental model: why personality is structural, not prose.
Why Ethos?Honest comparison vs. LangChain, CrewAI, OpenClaw, Hermes — when each fits, when each doesn't.
Architecture in 90 secondsThe 12-step AgentLoop.run() cycle, the four extension points, what's frozen vs. plug-in.
GlossaryEvery domain term in one place: personality, skill, tool, hook, session, memory scope, audience boundary.
Using Ethos — QuickstartInstall → first chat → ship a Telegram bot. Five minutes.
Building on Ethos — QuickstartWrite a tool, add a provider, build a channel adapter, publish a plugin. Ten minutes.
Built-in personalitiesWhat each of the five does, when to pick which, how to compose your own.
Memory modelMEMORY.md vs USER.md, per-personality vs. global scope, team memory.
Configure providersAnthropic, OpenAI, OpenRouter, Ollama, local LLMs.
Use Ethos as an MCP serverExpose personalities to Claude Desktop, Cursor, and other MCP clients.
Deploy on EC2A full production walkthrough including IAM, secrets, log rotation, backup.
Tool capability frameworkThe declarative contract every tool implements: network, secrets, storage, fs_reach, process.

Migrating from OpenClaw or Hermes

ethos claw migrate carries memory, skills, platform tokens, and provider keys from an existing OpenClaw or Hermes install into the Ethos layout. Dry-run first:

ethos claw migrate --dry-run     # preview the plan; touches nothing
ethos claw migrate               # apply

What moves cleanly:

  • MEMORY.md and USER.md → the new personality's memory scope, identical semantics.
  • SOUL.md (OpenClaw) → a migrated personality with SOUL.md derived from it; built-in matches resolve automatically (engineer.md lands on the built-in engineer, etc.).
  • Platform tokens (Telegram bot tokens, Slack app credentials, Discord tokens) → the new SecretsResolver with chmod 0600, referenced from config.yaml as ${secrets:slack/<bot>/botToken}.
  • Provider API keys → ~/.ethos/secrets/providers/<provider>/apiKey.
  • Skills directory → unchanged path semantics; OpenClaw-compat parses SKILL.md frontmatter, env substitutions, and OS gates, so existing clawhub skills install and run without modification.

Idempotent — safe to re-run. What does not move (and why is documented in the migration guide):

  • Anything that was inline plaintext in config.yaml migrates to the secrets resolver; the config file gets rewritten to use ${secrets:...} refs.
  • Personality boundary settings (fs_reach, safety.network.allow) are added on migration with safe defaults; review them before the first bot run.

Full migration reference: Migrate from OpenClaw →.

You can also stay on your existing setup and install Ethos-native skills into OpenClaw or Hermes — every Ethos skill is SKILL.md-shaped and runs unmodified. The migration command is for operators who want the full personality-is-architecture model.

Contributing

Three documents are mandatory reading before any non-trivial change:

DocWhen
CLAUDE.mdCodebase guide — architecture, conventions, gotchas, learnings. Read before writing code.
DESIGN.mdVisual system — tokens, typography, motion, per-surface mapping. Read before any UI work (web, TUI, VS Code, email templates).
.agents/skills/docs/SKILL.mdDocs system — page kinds, front-matter contract, voice rules, anti-patterns. Read before writing or editing any documentation.
.github/PULL_REQUEST_TEMPLATE.mdThe checklist your PR will be evaluated against.

Local setup:

git clone https://github.com/MiteshSharma/ethos
cd ethos
make prepare    # pnpm install + git hooks
make check      # typecheck + lint + test (mirror of CI)
make dev        # run the CLI from source

Repo layout:

packages/    @ethosagent/{types, core, plugin-sdk, plugin-contract, ...}
extensions/  llm-*, session-*, memory-*, platform-*, tools-*, gateway, ...
apps/        ethos (CLI), tui, vscode-extension, web, web-api
docs/        Docusaurus site — content/, plugins/, scripts/
plan/        Architecture notes, phase plans, completed plans

The CLI binary entry is apps/ethos/src/index.ts. Every extension point is a typed interface in packages/types/src/index.ts, injected into AgentLoop at construction. Core never imports concrete implementations.

Open an issue before non-trivial changes — alignment is cheaper than rework. Look for good-first-issue to find a starter task. Plugin authors: the plugin SDK quickstart shows how to publish a tool, hook, channel adapter, or memory provider as a standalone npm package.

Community

License

MIT

Ver o original no GitHub

Bom para

Relacionados