Chimera Agent

Chimera

The governed, self-evolving agent — proved and governed. Thinks with many minds, does real work on its own, learns only what's proven, and is safe by architecture.

[](https://pypi.org/project/chimera-agent/) [](LICENSE) [](https://www.python.org/) [](https://github.com/brcampidelli/chimera-agent/actions/workflows/ci.yml) [](https://mypy-lang.org/) [](https://github.com/astral-sh/ruff) [](https://discord.gg/ACvBbrmguV) [](https://www.reddit.com/r/ChimeraAgent/)

[](https://donate.stripe.com/9B63cofM491m4SBfe177O00)

English · Português · Español · Deutsch · Français · 中文 · 日本語

Most AI assistants bet everything on a single model and forget everything when the chat ends. Chimera does two things differently: for hard questions it asks several AI models at once and blends their answers into one stronger result, and it remembers and learns so it becomes more useful the more you use it. It doesn't just chat — give it a goal and it plans, uses tools, checks its own work, and keeps only what actually works.

> Free and open-source (Apache-2.0), in early but active development. It already works end to > end: chat with it, let it finish tasks on its own, run it as a bot on your favourite messaging app, > deploy it on a server so it works 24/7, and watch it learn from what it does. It's alpha — solid > and heavily tested (1000+ automated tests, strict type-checking and linting on every change), but > not yet battle-hardened in production.

---

Why Chimera

Think of most AI tools as asking one expert and hoping they're right. Chimera is like having a panel of experts that debate, a fair judge that weighs their answers, and a writer that delivers the best combined result — then a teammate who actually does the work and learns from it. Here's what makes it special, in plain terms:

• 🧠 Many minds, one answer. For tough questions, Chimera asks several models the same thing, lets one model compare their answers, and has a final model write the best combined response — so you get something more balanced and less likely to be wrong than any single model alone. (It does this only when it's worth it, to stay fast and cheap.)
• 🚀 It does the work, not just talk. Give it a goal. It breaks it down, uses tools, edits files, runs the tests, and keeps a change only if it passes. If something breaks, it undoes it and tries again — so it doesn't leave a mess behind.
• 🧬 It gets better the more you use it. It remembers your preferences and important facts across conversations, and quietly turns tasks it repeats into reusable skills. It's built to keep improving instead of slowly getting worse over long runs — a problem that quietly degrades many agents.
• 🛡️ Safe by design. Every risky action passes a safety check first, anything destructive asks for confirmation, and untrusted code can run in a locked-down, network-off container. (Those checks are a cheap first filter, not the real boundary — the sandbox is; and container isolation is opt-in. See [SECURITY.md](SECURITY.md).)
• 🔌 Any model, runs anywhere. Use big hosted models or your own local ones through a single interface — on your laptop or a $5 server, around the clock.
• 🧩 Truly yours. Open-source, no lock-in, no vendor account required. You run it, you own it, you can change anything.

How Chimera compares

Chimera doesn't try to out-channel the giant agent projects. It bets on the three things a real reverse-engineering study of five leaders (OpenClaw, Hermes, nanobot, CrewAI, LangGraph) found they all leave open — and makes them its core:

• 🧬 Self-evolution with a fitness signal. The others "learn" by appending whatever happened, or by human pull requests — nothing measures whether a learned change actually helped. Chimera keeps a change only when a verified result proves it did: the evolution step is gated on the real working-tree diff and an honest A/B, never the model's say-so.
• 🛡️ Security by architecture. Prompt injection is now widely considered unpatchable; the popular agents mitigate at the app layer or declare it out of scope (one shipped 135k publicly-exposed instances and a marketplace ~12% full of malicious skills). Chimera tracks taint provenance end-to-end, strips control tokens from untrusted content, narrows tool access on a tainted run, guards side-effecting retries, and runs untrusted code in an opt-in locked-down container.
• 📊 Honest, published benchmarks. ~20% of a popular leaderboard's "solved" cases are actually wrong. Chimera reports every number with a confidence interval — including the runs where it didn't win — and never re-rolls for significance. A recorded paired run shows the full loop tripling a weak model's pass rate (17% → 67%), reported one pair short of significance, honestly.

In one line: the governed, self-evolving agent — proved and governed. It's alpha, and it says so.

Features

🧠 Thinking & doing

• Blend several models into one answer (chimera fuse) — a panel of models, a judge that surfaces where they agree, disagree, or miss something, and a synthesizer that writes the final answer. A smart router only spends this extra effort on hard problems, and when the first models already agree it stops early — measured at ~20–28% fewer tokens with no loss of accuracy on our benchmarks. (Fusion / mixture-of-agents itself isn't unique — you'll find it in OpenRouter and other tools; the difference here is it's wired into the agent loop behind that cost-aware router and measured, not a model you pick.)
• Finish tasks on its own (chimera solve) — it plans, acts with tools, then verifies and reverts: it runs your check (e.g. tests) and keeps the change only if it passes, otherwise undoes it and retries. Optionally works on an isolated copy of your project so nothing is touched until it's proven.
• Teams of specialists (chimera crew, chimera crew-isolated) — several role-focused agents split one job. In isolated mode each works on its own private copy in parallel; safe edits are merged, clashes are flagged instead of silently overwritten, and a bad worker's changes can be rejected by a per-worker test. A supervisor can fold everyone's work into one unified report.
• Delegate and explore — any agent can hand a self-contained subtask to a fresh sub-agent that reports back only the result, keeping the main context clean. The Context Explorer (chimera explore) finds the right files and lines in a codebase and returns a short answer instead of dumping everything.

🧬 Memory & self-improvement

• Long-term memory — it keeps short-term, recent, factual, and about-you memories, plus a map of how things relate. It can store memories in a fast full-text database, carry a profile of your preferences into every chat, merge duplicate notes automatically, and gently suggest saving a preference when you mention one.
• Learns new skills — when it succeeds at the same kind of task more than once, it turns that into a tested, reusable skill automatically.
• Optional self-training (advanced) — it can record its own experience so you can later fine-tune a model from it. Off by default; nothing trains without you asking.

🔌 Connect & automate

• Talk to it anywhere — a terminal chat, a full-screen terminal app, or as a bot on Discord, Telegram, Slack, Signal, and WhatsApp. There's also a simple HTTP endpoint.
• Scheduling & proactivity — give it recurring jobs in plain language ("every morning, summarize the news"). With the built-in scheduler running, it acts on time, not only when you message it.
• Tools & integrations — read and write files, run shell commands, browse the web, and run code safely in a sandbox. Connect almost any web service (through its API) or external tool — including any MCP server ([guide + runnable example](docs/mcp.md)) — and import your setup from other agent tools you already use.
• Batteries included — web search, image generation, text-to-speech, email, calendar, code execution, and more, ready to switch on.

🚀 Run anywhere, safely

• Any model, one interface — hosted models or your own local ones, with automatic fallback if one is down and rotation across multiple keys.
• One-command server deploy — run it with Docker (or bare-metal) so it stays up and restarts on reboot. See [docs/deploy.md](docs/deploy.md).
• Safety kernel — a check on every action (allow / warn / block / ask), an opt-in network-isolated container for untrusted code (CHIMERA_SANDBOX=docker; the default local runner is not isolated), and a full audit log of what it did.

Quickstart

You need Python 3.11+ and uv (a fast Python installer).

1. Install — from PyPI:

pip install chimera-agent

That gives you the chimera command. (The examples below use uv run chimera for a from-source checkout — with a pip install, just run chimera ….) To hack on Chimera itself, clone the repo:

git clone https://github.com/brcampidelli/chimera-agent.git
cd chimera-agent
uv sync --extra dev

2. Add one AI provider key. The easiest is an OpenRouter key — one key unlocks 100+ models.

cp .env.example .env
# open .env and set, for example:  CHIMERA_OPENROUTER_KEYS=sk-or-...

3. Check everything is ready

uv run chimera doctor

4. Try it

uv run chimera chat                         # have a conversation (it remembers)
uv run chimera run "Explain what you can do in 3 bullets"
uv run chimera fuse "What's the best way to learn to cook?" --show-panel   # see several models blended
uv run chimera solve "add a hello() function to app.py and a test for it" --verify "pytest -q"

Run it on a server (so it works 24/7):

docker compose up -d      # gateway + scheduler; restarts automatically

Full guide (Docker or systemd, scheduling, backups, security): [docs/deploy.md](docs/deploy.md).

5. Do something real in 5 minutes: email triage. Point Chimera at your inbox and get a ten-second digest — read-only, classify URGENT / PERSONAL / NEWSLETTER / COLD-SALES, and optionally schedule it every morning:

uv run chimera workflow examples/email_triage/triage.yaml -w ./triage_workspace

Setup + daily scheduling + honest caveats: [examples/emailtriage/README.md](examples/emailtriage/README.md).

How it works

Give Chimera a task; it plans, thinks (blending models when the problem is hard), acts with tools, checks its own work and keeps only what passes, then learns from the result — feeding memory and new skills back into the next task.

flowchart TD
    U([You: a task or a question]) --> P[Understand & plan]
    P --> Q{Is it a hard problem?}
    Q -- yes --> FUSION[Ask several models· a judge compares them· a synthesizer writes the best answer]
    Q -- no --> ONE[Use one fast model]
    FUSION --> ACT[Act: use tools, files, the web,or delegate to sub-agents]
    ONE --> ACT
    ACT --> V{Did it work?run tests / checks}
    V -- yes --> KEEP[Keep the change]
    V -- no --> REVERT[Undo & retry with the lesson learned]
    REVERT --> ACT
    KEEP --> LEARN[Learn: save what matters to memory,turn repeated work into a reusable skill]
    LEARN --> U
    MEM[(Long-term memory)] -. recalls .-> P
    LEARN -. writes .-> MEM
    GOV[[Safety check on every action]] -. guards .-> ACT

Commands

Every command is chimera (or uv run chimera before installing).

chimera doctor / models / features    # check setup, list models, see optional capabilities
chimera chat                          # interactive assistant that remembers across turns
chimera tui                           # full-screen terminal app
chimera run "PROMPT" --image pic.png  # one-shot answer (can read an image)
chimera fuse "PROMPT" --show-panel    # blend several models: panel -> judge -> synthesizer
chimera solve "TASK" --verify "pytest -q" --isolate   # do a task; keep the change only if the check passes
chimera crew "TASK" --mode supervisor         # a team of specialists tackles one task
chimera crew-isolated "TASK" -W "name:role" --verify "..." --synthesize   # team, each in its own isolated copy
chimera explore "where is login handled?"     # find the right files/lines, get a short answer
chimera deliver "a launch plan" -o plan.md    # produce a polished document
chimera serve --cron [--discord|--telegram|--slack|--signal]   # run as a service: chat bot + scheduler
chimera cron add "brief" "0 8 * * *" "Summarize the news"       # schedule recurring work
chimera memory add / graph / consolidate      # long-term memory: save, relate, tidy up
chimera kanban add/board/run                   # a task board that dispatches work to the agent
chimera workflow flow.yaml                     # run a repeatable automation described in a file
chimera migrate   --apply         # import settings, skills, and memory from another agent tool
chimera evolve status / tune / recipe          # optional: self-optimize; prepare data to fine-tune a model
chimera fusion-bench / skillcard-bench / schema-bench / sandbox-bench   # honest A/B benchmarks: measure cost, quality & side effects before trusting a feature
chimera pet new --name Chimi                   # adopt a small virtual companion :)

See the [Usage Guide](docs/usage.md) for every command with copy-paste examples.

Architecture

Chimera is a Python package with clearly separated parts, so you can understand or extend any piece on its own:

chimera/
  core/          the agent loop: plan, act, verify, keep-or-undo, and isolated work copies
  fusion/        the "many minds" engine: panel -> judge -> synthesizer + the smart router
  memory/        short-term / recent / factual / about-you memory + a relationship graph
  skills/        the built-in skill library and how relevant skills are found
  evolution/     learning new skills from success, and the experience it learns from
  governance/    the safety kernel (allow/warn/block/ask), audit log, and change controls
  orchestration/ teams of agents: roles, crews, isolated parallel workers, unified reports
  ecosystem/     advanced self-improvement: agents that design agents, optional model training
  kanban/        a task board that hands cards to the agent
  workflow/      describe a repeatable automation in a simple file and run it
  tools/         built-in tools (files, shell, web, search) + code execution
  sandbox/       run tools locally or inside a locked-down container
  integrations/  connect external tools and any web API
  scheduler/     recurring jobs + the daemon that fires them on time
  migration/     bring your setup over from other agent tools
  providers/     one interface to every model, with fallback and key rotation
  interface/     the shared conversation engine (used by chat, the app, and bots)
  server/        the messaging gateway and HTTP endpoint
  cli/           the `chimera` command

See [docs/architecture.md](docs/architecture.md) for the full design.

Vision & goals

Chimera's goal is simple: an AI agent that anyone can run, that reasons better by combining many models instead of trusting one, that truly gets better the more it's used, and that stays safe and fully open along the way.

Most AI tools today are either smart-but-forgetful (they lose everything when the chat ends) or capable-but-closed (you don't control them). And many that try to "improve themselves" quietly get worse over long runs. Chimera is our attempt at a different path:

• Better thinking, not a bigger bill — combine several models only when it helps, so quality goes up without waste.
• Real memory and real skills — remember what matters and turn repeated work into reusable abilities.
• Improvement that lasts — resist the slow de

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: brcampidelli
• Source: brcampidelli/chimera-agent
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.