EvoNexus: the Claude Code CLI turned into a 38-agent business operating layer

What EvoNexus is for, and who it is not for

EvoNexus targets a specific gap: a single Claude Code CLI installation is one assistant in one terminal, and everything around it (recurring reports, meeting sync, email triage, community monitoring, financial tracking) is manual. The README describes the project as a multi-agent operating layer built around the Claude Code CLI protocol, running 38 specialized agents across two layers: 17 business agents covering operations, finance, community, marketing, HR, legal, product, data and learning retention, and 21 engineering agents covering architecture, planning, code review, testing, debugging, security, design, cycle orchestration and retrospective. Nineteen of the engineering agents are derived from oh-my-claudecode (MIT, by Yeachan Heo), and two, Helm and Mirror, are native to this project.

The intended user is a small team or solo operator who already pays for an LLM backend and wants the orchestration layer without building it. The README is explicit that this is not a chatbot, and the emphasis on routines, HTML reports and a unified dashboard supports that framing. What it is not: a hosted service, an SDK, or a product with a vendor behind it. The disclaimer at the top of the README states the project is independent and unofficial, not affiliated with, endorsed by, or sponsored by Anthropic, and that users supply their own installation and credentials. Anyone looking for a supported platform contract should stop reading there.

How the agent layer actually works: markdown files, not code

The mechanism is unusual for an agent framework and worth understanding before installing anything. Agents are `.md` files containing system prompts, not Python classes. The README states that adding an agent means dropping a file into `.claude/agents/`, and the docker-compose file mounts `./.claude/agents`, `./.claude/skills`, `./.claude/commands` and `./.claude/templates` into the dashboard container as read-only volumes, which confirms that the agent definitions live on the host filesystem and are read at container start rather than baked into the image.

Skills follow the same pattern. The README describes 190+ skills organized by domain prefix (`social-`, `fin-`, `int-`, `prod-`, `mkt-`, `gog-`, `obs-`, `discord-`, `pulse-`, `sage-`, `hr-`, `legal-`, `ops-`, `cs-`, `data-`, `pm-`, `dev-`), which means the taxonomy is encoded in filenames. That is cheap to extend and cheap to break: a skill with the wrong prefix will not be discovered by whatever code filters on the prefix, and the repository layout gives no schema file that would catch the mistake. The engineering layer follows what the README calls a canonical 6-phase workflow documented in `.claude/rules/dev-phases.md`.

State lives outside the agents. The README describes a two-tier memory system (`CLAUDE.md` plus a `memory/` directory) using an LLM Wiki pattern, and the Dockerfile declares persistent volumes for daily logs, projects, community, finance, personal, meetings and strategy directories. Routines are separate again: 7 core plus 20 custom daily, weekly and monthly ADWs managed by `scheduler.py` at the repository root. Slash commands such as `/clawdia`, `/flux`, `/pulse` and `/apex` invoke agents from the terminal. The practical consequence is that the whole system is inspectable as text, and equally that nothing validates it at build time.

Installing EvoNexus and running a first routine

The README points at a Quick Start section and the repository ships a setup wizard. `setup.py` documents its own usage as generating workspace configuration, `CLAUDE.md`, `.env` and the folder structure, and the Makefile exposes a `setup` target. Because the wizard writes `.env`, the `.env.example` file at the repository root is the place to look for the variable names before running it.

python setup.py
# or: make setup

Running the wizard interactively produces the workspace layout and the environment file. The same script detects when it is being invoked by pip or npx through the `EVO_NEXUS_INSTALL=1` environment variable or setuptools argv markers such as `egg_info` and `bdist_wheel`, and in that case skips the interactive prompts entirely. If you expect a wizard and get silence, that detection is why.

The container route is shorter if you already have Docker. The compose file defines a dashboard service built from `Dockerfile.swarm.dashboard`, publishing port 8081 on the host against 8080 in the container, plus 32352 for the terminal server, with `EVONEXUS_PORT=8080` and `TERMINAL_SERVER_PORT=32352` set as environment variables.

docker compose up -d
curl -f http://localhost:8080/api/version

The healthcheck in the compose file is exactly that `curl` against `/api/version`, so hitting it manually tells you the same thing the orchestrator checks every 30 seconds. A successful response means the Flask backend is up. Note the port mapping: from the host you reach the dashboard on 8081, not 8080.

A first real use is a routine rather than a chat. `ROUTINES.md` at the repository root is the file that documents them, and `scheduler.py` is the process that dispatches them. The README states routines produce JSONL logs, execution metrics and cost tracking per routine, so the first thing to inspect after a scheduled run is the log output under the mounted `ADWs/logs` volume, which the compose file maps from `./ADWs/logs` on the host.

The provider story and where it strains

EvoNexus defaults to Anthropic's `claude` CLI and switches to OpenAI, Google Gemini, OpenRouter, AWS Bedrock, Google Vertex AI or Codex Auth through OpenClaude, an npm package published as `@gitlawb/openclaude`. The Dockerfile installs both CLIs globally and pins OpenClaude to `@latest` with a comment stating the minimum supported version is 0.3.0, the first release carrying a Codex shortcut endpoint fix. The README frames this as no vendor lock-in: same agents, same skills, same workflows, your choice of backend.

The strain is in the dependency chain. Multi-provider support is not implemented inside EvoNexus; it is delegated to a third-party npm package that the Dockerfile deliberately does not version-pin, only floor-pin. A breaking change in `@gitlawb/openclaude` reaches a fresh `docker compose build` immediately. For a project whose value proposition is that you can swap backends without touching a line of code, the layer that performs the swap is the least pinned piece of the stack. Teams that care about reproducible builds should pin the OpenClaude version in their own image rather than inheriting `@latest`.

The second constraint is credential handling. The compose file mounts a named volume `claude-auth` at `/root/.claude`, so CLI authentication state persists across container restarts. That is convenient and also means the container holds a live credential for whichever provider you configured. The README's claim that your data never leaves your infrastructure is about the orchestration layer; prompts still go to whichever model provider you selected.

Where EvoNexus is the wrong tool

The clearest failure mode is the licence mismatch. The README renders an Apache 2.0 badge and links to opensource.org/licenses/Apache-2.0, while the repository metadata reports the licence as NOASSERTION. A `LICENSE` and a `NOTICE` file both exist at the root, so the text is presumably there, but GitHub has not classified it. If your organisation gates dependency adoption on machine-readable licence metadata, that discrepancy will stop you before any technical review begins, and resolving it means reading the LICENSE file yourself rather than trusting the badge.

The second case is anything requiring a stable programmatic contract. The project exposes a CLI entry point, `evonexus = "dashboard.backend.knowledge.cli:main"`, which points at the knowledge subsystem, not at a general agent API. Agents are markdown files and skills are markdown files; there is no schema, no typed interface and no versioned plugin API described in the README beyond the plugin system mentioned for packaging reusable bundles. The most recent release listed is v0.33.0, labelled the plugin contract release, which tells you the extension surface is still moving. If you need to call agents from your own service, you are building on an interface that the project itself is still defining.

The third case is scale. The scheduler is `schedule` plus `scheduler.py`, a single Python process. The README describes heartbeats as agents that wake on a schedule, run a 9-step protocol and decide whether to act. That model suits a handful of daily and weekly routines. It is not a job queue, and nothing in the repository layout suggests distributed execution.

How it compares to oh-my-claudecode and to a plain Claude Code setup

The honest alternative is the project EvoNexus partly derives from. The README states that 19 of the 21 engineering agents come from oh-my-claudecode (MIT, by Yeachan Heo). If your interest is exclusively the engineering workflow, architecture review, planning, testing, debugging and retrospective, then oh-my-claudecode is the narrower dependency and you skip the business layer, the dashboard, the integrations and the Flask stack entirely. The difference in approach is scope: oh-my-claudecode is an engineering agent collection, while EvoNexus positions itself as an operating layer that also covers finance, community, legal, HR and customer success, and consolidates them into one dashboard.

The second alternative is no framework at all. A plain Claude Code installation with a hand-written `CLAUDE.md` and a couple of shell scripts covers a surprising amount of what the 7 core routines do. What you give up is the scheduler, the per-routine cost tracking, the web terminal, the role-based dashboard auth and the 19+ integrations the README lists (Google Calendar, Gmail, Linear, GitHub, Discord, Telegram, Stripe, Omie, Bling, Asaas, Fathom, Todoist, YouTube, Instagram, LinkedIn, Evolution API, Evolution Go, Evo CRM). The integrations are the real differentiator, and they are also the part most likely to break quietly when a third-party API changes, since MCP servers are external processes.

A third option worth naming is the knowledge base path. Semantic search is optional and delegated to MemPalace, described in the README as local ChromaDB vectors with a one-click install. If retrieval over your own documents is the only thing you want, that is a much smaller commitment than the full stack.

Maintenance, upgrade cost and licence implications

The last push to the repository was on 2026-05-13, roughly four months before this writing. The most recent release listed is v0.33.0 from 2026-04-26, with v0.32.3 and v0.32.2 in the two days before it. That cadence suggests a project that was shipping frequently through late April and then slowed, and the repository is not archived. The version in `pyproject.toml` reads 0.32.3 while the latest release is v0.33.0, a drift worth noting if you plan to check versions programmatically.

Upgrade cost concentrates in three places. The `@latest` pin on OpenClaude means image rebuilds can change provider behaviour without a version bump in this repository. The plugin contract introduced in v0.33.0 is the newest extension surface, so plugins written against it have the least history. And the Docker Compose topology has several variants (`docker-compose.yml`, `docker-compose.dev.yml`, `docker-compose.hub.yml`, `docker-compose.proxy.yml`, plus `evonexus.stack.yml` and four Dockerfiles), which means a change to the base image has to be reconciled across more than one deployment path.

On licensing: the README displays an Apache 2.0 badge, but the repository metadata reports NOASSERTION and a `TRADEMARKS.md` file exists alongside `LICENSE` and `NOTICE`. The README's own disclaimer states the project is unofficial and that Claude and Claude Code are trademarks of Anthropic, PBC. Redistributing or rebranding the project is where the trademark file matters, and that is a question for your own counsel, not something the README resolves.

Editorial conclusion

Adopt EvoNexus if you already run the Claude Code CLI or OpenClaude locally and want scheduled routines, markdown-defined agents and a dashboard without writing an SDK integration. Do not adopt it if you need a stable public API, provider-neutral licensing clarity, or an agent framework you can embed in your own product; the README itself calls the project unofficial. Verify first: whether the LICENSE file matches the Apache 2.0 badge the README shows, since the repository metadata reports NOASSERTION, and whether the plugin contract introduced in v0.33.0 matches the version pinned in your deployment.

Frequently asked questions

Official sources

1. evolution-foundation/evo-nexus on GitHub
2. Issues
3. Project website
4. README
5. Releases