ilearn-lab/evoharness

English | ZH-CN

EvoHarness delivers terminal-native agent infrastructure: tools, commands, skills, agents, plugins, MCP, memory, approvals, and controlled self-evolution.

Build with the project: shape an open, visible, and research-grade harness for coding workflows.

🧠✨ Controlled Self-Evolution (-_-)

🌌 Evidence, operators, candidate patches, and promotion paths 🩵

EvoHarness treats self-evolution as control over the harness surface, not as unconstrained agent autonomy.

The real question is not “can the model rewrite itself once,” but:

• 🧾 when to evolve: use real sessions, traces, failures, approvals, and workspace state as evidence
• 🎛️ which operator to choose: revise_command, revise_skill, distill_memory, grow_ecosystem, or stop
• 🛑 when not to evolve: low-value changes should be filtered before mutation
• ✅ how changes enter the runtime: candidate patches must pass validation, then get promoted, held, or rolled back

So the loop can be read in one line:

evidence -> operator choice -> candidate patch -> validation -> promote / hold / rollback

In short, EvoHarness studies self-evolution as a long-horizon operator-control problem over commands, skills, agents, plugins, MCP, memory, and policy surfaces.

🐴 Three-stage mascot evolution: saddle -> harness -> elegant evolution ✨🩵

---

🧩🛠️ Harness Architecture (^_^)/

🧩 One runtime core • 👀 visible harness surfaces • 🧠 one long-horizon state layer

EvoHarness is built around one architectural bet: the harness should be a first-class system surface, not hidden orchestration glue.

What makes the architecture distinctive:

• 👀 visible by default: tools, commands, skills, agents, plugins, and MCP stay inspectable in the workspace
• 🧱 workspace-native: markdown, registries, settings, memory, and policy surfaces live as real project artifacts
• 🧠 long-horizon aware: approvals, archived sessions, analytics, and evolution planning remain in the same runtime
• 🧪 research-ready: the harness is observable, countable, and evolvable instead of disappearing behind a black box

At the system surface, EvoHarness exposes:

• 🛠️ 27 tools for files, shell, search, tasks, registry, MCP, and subagents

• 📜 32 commands as workflow entry points

• 🧠 34 skills as on-demand procedural guidance

• 🤖 32 agents for bounded delegation

• 🔌 7 plugins for workspace-native ecosystem growth

• 🛰️ 11 MCP servers / 29 MCP tools for external tools, resources, and prompts

  🦄 A guided peek: tools, commands, skills, agents, plugins, and MCP all meet at the runtime core ✨

If you want to understand the project quickly, start here:

• 🚀 run evoh doctor --workspace . to inspect the resolved runtime surface
• 🧭 run evoh tools-list --workspace ., evoh commands-list --workspace ., evoh agents-list --workspace ., and evoh mcp-list --workspace . --kind all
• 🧠 use /help, /commands, /skills, /agents, and /mcp once you enter the session
• 🧩 browse plugins, .claude, and .evo-harness/mcp.json to see the harness as a real workspace product

In short: EvoHarness is not just “an agent with tools”; it is a visible, editable, and evolvable harness workspace (^_^)

---

🚀 Quick Start (^o^)/

🧰 What You Need

Without Node, EvoHarness still opens the text session (^_^)/

1. 🔍 Install and Inspect

git clone https://github.com/HITSZ-DS/EvoHarness.git
cd EvoHarness
python -m pip install -e .
evoh doctor --workspace .

If the doctor report looks healthy, you are ready to enter the harness.

2. 🚀 Start the Session

evoh --workspace .

If npm is available, EvoHarness will try the React/Ink frontend first.
If not, it falls back to the text session automatically.

✨ First look: runtime deck, slash commands, and live harness status in one terminal surface

3. 🛠️ Configure Your Provider with /setup

Inside the session, run:

/setup

EvoHarness will ask for four things:

• 🧩 Provider profile: which API family or gateway style you want

• 🤖 Model: the exact model name you want to use

• 🔑 API key: paste it now, or leave it blank if you already keep it elsewhere

• 🌐 Base URL: required for custom gateways and non-default endpoints

  🛠️ /setup is the fastest way to make a fresh session actually usable

🧭 Which Provider Profile Should You Choose?

💡 New: Local & Low-Cost Options!

• 🆓 claude-code-cli: Use your Claude Code subscription instead of API keys
• 🆓 ollama: Run completely free open-source models locally (Llama 3, Qwen 2, etc.)
• 💰 codex: OpenAI Codex for code-specific tasks

See LOCAL_PROVIDERS.md for detailed setup instructions.

Recommended pattern:

• 🔐 keep your key in an environment variable when possible
• 🧭 use /setup to choose the profile, model, and base URL
• 🧱 use evoh init if you want those settings scaffolded into a fresh workspace

Quick key rules:

• anthropic and anthropic-compatible typically use ANTHROPIC_API_KEY
• moonshot typically uses MOONSHOT_API_KEY
• openai-compatible defaults to OPENAI_API_KEY, unless you scaffold a custom one with evoh init --api-key-env ...

4. 🧱 Scaffold EvoHarness into Your Own Repository

If you want to bring EvoHarness into another project instead of only running this repo:

evoh init --workspace . --provider-profile openai-compatible --model glm-5 --api-key-env ZHIPUAI_API_KEY --base-url https://open.bigmodel.cn/api/paas/v4/

This creates CLAUDE.md, .evo-harness/settings.json, starter .claude/ assets, and the local MCP registry.

Useful follow-up checks:

evoh provider-detect --workspace .
evoh provider-template --profile openai-compatible --model glm-5
evoh doctor --workspace .

🧪 Helpful First Commands

evoh doctor --workspace .
evoh tools-list --workspace .
evoh commands-list --workspace .
evoh agents-list --workspace .
evoh mcp-list --workspace . --kind all
evoh provider-detect --workspace .

💬 Helpful Session Commands

/help
/setup
/login
/doctor
/plugins
/resume
/permissions
/exit

---

🕸️🔌 Plugin and MCP Ecosystem (^o^)/

🔧 installable workflow bundles • 🛰️ MCP-native utilities • 🧩 one visible workspace ecosystem

EvoHarness treats plugins and MCP as part of the product surface, not as sidecar extras.

What that means in practice:

• 🔌 plugins bundle commands, skills, agents, and MCP surfaces around one workflow family
• 🛰️ MCP bundles expose reusable tools, resources, and prompts for docs, sessions, quality, and workspace mapping
• 🧱 everything stays workspace-native, so users can inspect the ecosystem instead of guessing what exists

✨ Bundled Plugin Families

🛰️ Core MCP Surfaces

📡 Current Ecosystem Surface

🧭 How to Explore the Ecosystem

Inside the session:

/plugins
/plugins marketplaces
/mcp
/commands
/agents
/skills

From the CLI:

evoh plugins-list --workspace .
evoh marketplaces-list --workspace .
evoh marketplace-plugins --workspace .
evoh mcp-list --workspace . --kind all

---

🎛️🧭 Modes and Commands (•‿•)

🧠 provider + model • 🔐 permission mode • 🧩 active workflow command • 📡 live surface counts

Once the session opens, EvoHarness keeps its operating state visible in the runtime deck instead of hiding it.

The main runtime fields mean:

Permission modes are simple:

Command layers are also explicit:

Good first commands inside the session:

/help
/doctor
/commands
/skills
/agents
/mcp
/permissions
/read-only-inspect auth flow

If you want the same view from the CLI before chatting:

evoh commands-list --workspace .
evoh agents-list --workspace .
evoh tools-list --workspace .
evoh mcp-list --workspace . --kind all

---

📄 License

Apache-2.0. See LICENSE.

🙇‍ Thanks

Linux.do