Rugol — Orquestrador de Agentes IA
EduardoMoraga/rugol
Orquestrador de agentes Claude com foco em decisões melhores, não mais informação
Ver no GitHubPlataforma de operações com agentes Claude que funciona como central de controle local para equipes de IA. Organiza agentes especializados em projetos com missões claras, regras vivas e desafio contínuo de pensamento, permitindo que você tome decisões melhor informadas e com menos ruído.
Instalação
npx convez-ai EduardoMoraga/rugol1 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
Casos de uso
- Assistentes pessoais e produtividade com equipes de agentes
- Geração de conteúdo educativo (jogos, materiais didáticos interativos)
- Gestão de marca pessoal com múltiplos agentes especializados
- Pipelines de vendas e operações com desafio estruturado de decisões
Veredito

Rugol inverte o paradigma típico de plataformas de agentes ao priorizar projeto-missão em vez de agentes isolados, com rastreamento de lições aprendidas e validação por devil's advocate. Abordagem inovadora baseada em economia comportamental, ideal para não-desenvolvedores que precisam de orquestração multi-agente com estrutura decisória clara.
README
A tradução para o português deste README ainda está na fila.
Rugol
Your AI agent orchestrator — support for the decisions that matter.
A local control room where teams of Claude agents do the work, challenge your thinking, and remember what you've learned — so you decide with a better process, not just more information.
Quickstart · Why Rugol · Real cases · How it works · Español
Good decisions aren't about more information — they're about a better process.
Rugol flips the paradigm. You don't think "what agent should I create". You think what do I want to get done: a personal assistant, your brand, helping your daughter learn biology through games, your sales pipeline. Each one comes with its own team of specialist agents, a written mission, and living rules. The agents do the work and challenge your thinking — you keep the decision, better informed and with less noise.
Why Rugol
Built by a business person, not a dev
I'm an economist. I lead Business Intelligence projects across LATAM. I watched "agentic AI" get trapped in technical jargon that excludes the very people the tool can change life for.
Rugol was born from that frustration. Behind the code (which I wrote with Claude Code, naturally), the product decisions come from a different place: behavioral economics, real productivity problems, everyday life.
The project-first paradigm
| Other platforms | Rugol |
|---|---|
| Flat list of standalone agents | Projects as departments with mission |
| You pick the model (haiku/sonnet/opus) | You pick the task type (heuristic / think / deliberate); the system routes |
| Agent acts alone | Optional: devil's advocate challenges before acting |
| Memory per-agent or none | Living lessons per project — every team member reads them before each task |
| Technical templates | Emotional templates: "personal assistant", "my daughter learns through games" |
Three behavioral economics principles, embodied in software
| Principle | How it shows up in Rugol |
|---|---|
| System 1 vs System 2 (Kahneman) | The user doesn't think in models. They pick Heuristic (haiku, fast), Think (agent's model) or Deliberate (opus, hard-to-reverse decisions). |
| Noise (Kahneman/Sunstein) | Before important decisions, "Devil's advocate" (opus) challenges the primary answer. Two perspectives, you decide. |
| Biases | Each project keeps a living list of lessons (lesson / bias / fact). Every team member reads it before each run. What you learned the hard way becomes a permanent anchor. |
Real cases
"My daughter learns through games"
My 9-year-old had a biology test. In 5 minutes, two agents (designer Haiku + builder Sonnet) generated an HTML+JS mini-game about photosynthesis. No libraries, no install, double-click and play. She learned without realizing it. She studied while laughing.
It's a built-in template. A mom who's only ever used ChatGPT can clone it, write "this week's topic is cells", and get a fresh game in minutes.
"My personal brand"
Three agents that take care of public voice: brand-architect (Opus, decides what's on-brand), content-editor (writes the posts), market-analyst (measures what resonates). Living lessons like "never say 'leverage'" or "zero hype" get injected into every run, so the team doesn't drift even when you're not watching.
"Sales pipeline"
For freelancers and founders who run sales in a spreadsheet: prospector + qualifier + follower-upper. Daily schedule that drops no active follow-up. Honesty about fit: if we're not the right vendor, the system says so.
"Personal assistant"
Morning brief, inbox triage, end-of-day capture. The invisible team that takes care of your day.
"Topic researcher"
When you need to master something new in a week: researcher gathers sources, explainer translates them into everyday analogies, critic challenges the consensus. Takes you from 0 to being able to hold an informed conversation.
How it works
Three concepts. That's it.
1. Project = department with a mission
Each project has a name, a color, an icon, a written mission (the why), and a 1-5 agent team. Every team member reads the mission before each task — it's an anchor against drift.
2. Living lessons
When the team learns something (a bias spotted, a decision made, a business rule), you add it as a lesson to the project. Next time any team member works, they'll read it. The project's memory grows without anyone losing context.
Every assistant answer and every devil's advocate critique exposes a "Promote to lesson" button — one click and that learning becomes a permanent anchor.
3. Task type + devil's advocate
Above each chat input:
- Heuristic → routed to haiku, fast and cheap.
- Think → agent's own model, the default.
- Deliberate → routed to opus, deep reasoning.
And a "Request devil's advocate" checkbox: after the answer, a second agent (opus) challenges it specifically. Two perspectives for the decisions that matter.
The Soul Layer
Every agent registered in Rugol inherits a stack of capabilities that turns it from "a prompt with a model" into something with continuity. You don't configure this — it's the platform's default.
- Identity — every run starts with "you are X, you've been here N times before, this is what we've worked on together". The agent sounds like itself across runs because it always knows who it is.
- Proactive memory — the agent has three tools it can call on
its own:
save_memory,list_my_memories,forget_memory. It reads explicit rules about when to save (user facts, feedback, project state, external references) and what NOT to save. The memory persists across runs as plain markdown inagent-memory/. - (Roadmap) Dual-track dispatch — a Haiku classifier routes every request to System 1 (fast, cached) or System 2 (deliberate, Opus, plan-then-execute). Kahneman, made executable.
- (Roadmap) Evolutionary archive — each agent's system prompt has a tree of versions, each validated empirically against past runs. Inspired by the Darwin Gödel Machine (arXiv:2505.22954). Open-ended self-improvement, with the human always in the loop.
See docs/adrs/ADR-006-soul-layer.md
for the design, plus ADR-007 and ADR-008 for the future sprints.
Quickstart
No prerequisites. The installer brings its own runtimes (an isolated Python via uv, and Node) — you don't need Python, Node, or Docker preinstalled. One line, then a wizard.
Mac / Linux
curl -fsSL https://raw.githubusercontent.com/EduardoMoraga/rugol/main/installer/install.sh | bash
Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/EduardoMoraga/rugol/main/installer/install.ps1 | iex
Then, from any terminal:
rugol setup # auth + model + optional Telegram (the wizard walks you through it)
rugol up # builds, starts core + dashboard, opens your browser
Auth, either way, runs headless. Use your Claude Pro/Max plan
(the wizard runs claude setup-token and stores a long-lived token — no
per-use cost), or a dedicated API key (isolated billing). Everything
runs locally under ~/.rugol; nothing of yours leaves your machine.
That's it — the dashboard opens at http://localhost:3000 with five
ready-to-clone agent templates. Everything you create lives in
~/.rugol, so updates never touch your data.
| Command | What it does |
|---|---|
rugol setup | First-run wizard → writes your config |
rugol up / down | Start / stop the whole stack |
rugol status | Service health at a glance |
rugol logs [core|dashboard] | Live logs |
rugol doctor | Check runtimes, ports, config |
rugol update | Pull latest + rebuild (data untouched) |
rugol bot [list|add|remove] | Telegram bots, one per project (own token, own agent) |
rugol vault [agent] | Open the agents' memory as an Obsidian vault (graph view) |
rugol evolve <agent> | Self-improving: the agent proposes prompt upgrades, you approve |
rugol sessions [filter] | Your Claude Code sessions per project + how to resume them |
rugol autostart [on|off] | Start Rugol automatically at login (launchd / Scheduled Task) |
rugol uninstall | Remove it (asks before deleting data) |
Chat from minute one. setup asks for a default agent (assistant),
so if you drop in a Telegram token you can message your bot and it just
answers — no /bind, no menus. Want a specific agent on that chat later?
/bind <name> or reassign it in the dashboard. Token → chat, with a full
control panel waiting when you need depth.
Needs Python 3.12+, Node 20+, and claude /login done once.
git clone https://github.com/EduardoMoraga/rugol.git
cd rugol
# Backend
python -m venv .venv
source .venv/bin/activate # PowerShell: .\.venv\Scripts\Activate.ps1
pip install -r core/requirements.txt
cp .env.example .env # set USE_SUBSCRIPTION=true if you have Pro/Max
uvicorn core.main:app --host 127.0.0.1 --port 8000
# Frontend (separate terminal)
cd dashboard && pnpm install && pnpm dev
Or just docker compose up --build from the repo root.
What's already inside · v0.8.0-alpha
Rugol was built in layers, each shipped as a working, tested commit. The current version includes:
| Capa | What it adds |
|---|---|
| 1 | Project-first model, non-destructive migration, /projects as home |
| 2 | Multi-turn chat with cross-turn memory, clickable markdown + syntax highlight |
| 3 | Living lessons per project + auto self-improvement trigger (Hermes-style) |
| 4 | System 1/2 (task type selector) + optional devil's advocate |
| 5 | Per-agent tool whitelist + Architect dir picker |
| 6 | 5 curated project templates, one-click clone, auto-rename for duplicates |
| 7 | "Promote to lesson" everywhere — chat, advocate critiques, self-improvements |
| 8 | Per-agent MCP servers (stdio/sse/http) — connect Asana, Notion, Slack per agent |
| 9 | Ant farm with project clusters (visualization) |
| 10 | Emotional first-time onboarding |
| 11 | Extended health check + DEVELOPMENT.md |
| 13 | Telegram + Slack adapters with channel bindings + reply-on-completion |
| 14 | Reset to clean state (script + admin endpoint + Settings button) — install on a new PC in minutes |
| 15 | EN/ES toggle in the nav rail (persisted in localStorage) |
| 16 | Soul Layer — Sprint 1: identity + proactive memory tools, every agent inherits them automatically (ADR-006) |
| 17 | Soul Layer — Sprint 2: dual-track dispatcher (S1/S2 routing via Haiku classifier) + opt-in plan-then-execute (ADR-007) |
| 18 | Soul Layer — Sprint 3: per-agent evolutionary archive — propose/validate/accept mutations of system prompts (ADR-008) |
| 19 | Memory network (/memory-graph): Obsidian-style force-directed graph of every agent's memories and the [[wikilinks]] they weave — watch the fleet's knowledge grow live |
Full history in CHANGELOG.md. Technical detail in
DEVELOPMENT.md and the ADRs at docs/adrs/.
To install on a fresh PC see docs/install-on-new-pc.md.
Stack
- Backend: Python 3.12, FastAPI, async SQLAlchemy, SQLite (Postgres optional), APScheduler, claude-agent-sdk.
- Frontend: Next.js 15 + React 19 + Tailwind CSS v4, react-query, react-markdown, HTML5 Canvas for the ant farm.
- LLM auth: Claude Pro/Max subscription or API key — your call, per project.
- Local-first: everything runs on your machine. No telemetry by default.
For developers
If you're contributing or forking, read DEVELOPMENT.md first. It captures the stack, migration rules, known bugs (with tested workarounds), an architecture cheatsheet, and a map of which file implements which Capa.
Pull requests welcome. Issues with real use-cases (especially from non-technical people) are even more welcome — they're the material that tells us which template is missing.
Next on the roadmap
- Capa 8 — Per-agent MCP servers (connect Asana, Notion, Slack, Gmail per agent without touching the global .env).
- Telegram + Slack adapters — chat with any agent from your phone, with the adapter wired per-project.
- Additional Spanish templates — "My restaurant business", "Customer support for my online store", more LATAM cases.
- Windows
.batinstaller — one line for zero-code users.
License
MIT. Do what you need.
Crafted by Eduardo Moraga (eduardo.moraga.o@gmail.com) — economist, BI lead at Increxa, AI public speaker in LATAM.
If this helped you, tell me what project you used it for. That's what moves the roadmap.