CrewHaus is a meta-harness compiler designed to transform a single high-level specification (crewhaus.yaml) into multiple runtime targets. This versatile tool enables developers to compile one agent spec into various forms such as CLI agents, channel bots, RAG pipelines, multi-agent crews, eval harnesses, voice agents, and browser/computer-use agents.
Key Features:
Multi-target Compilation: Supports a wide range of runtime targets including CLI, channel bots (Slack, Discord, Telegram, WhatsApp, iMessage), RAG pipelines, multi-agent crews, eval bundles, voice/realtime agents, and browser/computer-use agents.
Active Evaluation Optimization: Automatically generates spec patches from eval failures to improve agent performance across all compiled targets.
Trust-aware Design by Default: Implements a security fabric with trust classification for untrusted content, ensuring robust protection across all runtimes.
Audience & Benefit:
Ideal for AI developers and researchers working with large language models (LLMs), CrewHaus allows you to write an agent once and compile it into various shapes as needed. This eliminates the need for separate configurations for each target, streamlining development processes. The active eval optimization feature automates improvements across all compiled agents, while the trust-aware design ensures consistent security across different runtimes.
CrewHaus is available via winget for easy installation.
README
CrewHaus Factory
The open-source meta-harness compiler for AI agents.
Compile a single spec (a crewhaus.yaml) into a CLI agent, channel bot, RAG pipeline, multi-agent crew, eval harness, voice/realtime agent, browser/computer-use agent, and more. Active eval optimization. Trust-aware by default. Apache-2.0.
> ★ If CrewHaus is useful to you, star the repo. For an independent, Apache-2.0 project maintained in the open, a star is the clearest signal the work is worth continuing.
# Install the standalone binary — no runtime required:
brew tap crewhaus/tap && brew install crewhaus # macOS / Linux (Homebrew)
# Windows: scoop install crewhaus · winget install CrewHaus.CLI
# Debian/Ubuntu (apt) and npm/Bun: see "Install" below
crewhaus --version
crewhaus init my-agent
cd my-agent
crewhaus compile crewhaus.yaml -o build && crewhaus run crewhaus.yaml
crewhaus is open source under Apache-2.0 and published as a bare package on npm,
Homebrew, Scoop, winget, and apt — see Install.
Install
The fastest path is the self-contained binary — one file, no Bun/Node required:
Prefer npm? The crewhaus package runs on Bun ≥ 1.2:
npm install -g crewhaus # global
bun add -d crewhaus # project-local dev dependency
Then confirm your install:
crewhaus --version
You can also grab a binary directly from the GitHub Releases page.
Why CrewHaus?
Write the agent once, as a spec (crewhaus.yaml). Compile it to the shape each situation calls for — a CLI to run locally, a Slack bot for the team, an eval bundle to grade it — each emitted as code idiomatic to that runtime, not a generic wrapper.
When the spec changes, every shape recompiles. Run the eval loop and crewhaus optimize rewrites the spec from its failures, so the fix lands in all of them. CrewHaus is the layer above the runtimes.
The compiler is the protagonist. Specs flow through parseSpec → lower → applyPasses → emit. The IR is a discriminated union of target-shape variants; each emitter consumes its own typed variant.
Eval is active, not passive. Eval failures produce spec patches. crewhaus optimize searches the mutation space (rule-based or Claude-driven) and writes back through a YAML CST that preserves comments and key order. The loop closes.
Security is a fabric, not a perimeter. Untrusted content — MCP responses, sub-agent returns, channel inbound messages, federation payloads, skill bodies, compaction summaries — is classified by a single boundary classifier, tagged with TrustOrigin, before it reaches a model call. Authentication verifies who; classification verifies what.
Install crewhaus (see Install) — the binary needs no runtime; the npm package needs Bun ≥ 1.2.
# Create a new agent project — writes a minimal `crewhaus.yaml`
crewhaus init my-agent
cd my-agent
If you'd rather develop against the workspace directly (contributing to factory itself), see CONTRIBUTING.md for the clone-and-link workflow.
crewhaus init writes a runnable starter spec:
# crewhaus.yaml
name: my-agent
target: cli
agent:
model: claude-opus-5
instructions: |
You are a helpful assistant. Replace these instructions with your
agent's actual behavior, persona, and constraints.
Edit the instructions block to describe what your agent should do, then:
# Set a provider credential — the default model is Anthropic; the full
# provider matrix (OpenAI, Gemini, Bedrock, Vertex, Azure, Groq/Together/
# OpenRouter/…, and local servers via local/@) is in
# packages/model-router/README.md and factory/.env.example.
export ANTHROPIC_API_KEY=sk-ant-...
# Compile crewhaus.yaml to a runnable bundle in ./build
crewhaus compile crewhaus.yaml -o build
# Run the agent
crewhaus run crewhaus.yaml
To compile to a different shape, change target: in crewhaus.yaml to one of the values from the table above (channel, pipeline, eval, …) and re-run crewhaus compile.
Example: one spec, multiple shapes
The two specs below share an identical agent: block — only target: changes. The same agent compiles to either a local CLI or a browser/computer-use agent, with no other config.
# cli.yaml — runs in a terminal
name: research-assistant
target: cli
agent:
model: claude-sonnet-5
instructions: |
You help users research a topic. Given a question, produce a
short, cited summary. If you have browser tools, start by calling
Navigate to load https://duckduckgo.com/html/, then use Screenshot
to read what came back before answering.
# browser.yaml — same agent, driven against a real browser
name: research-assistant
target: browser
agent:
model: claude-sonnet-5
instructions: |
You help users research a topic. Given a question, produce a
short, cited summary. If you have browser tools, start by calling
Navigate to load https://duckduckgo.com/html/, then use Screenshot
to read what came back before answering.
# Compile to runnable bundles
crewhaus compile cli.yaml -o build/cli # local CLI agent
crewhaus compile browser.yaml -o build/browser # browser/computer-use agent
# Or run directly — no compile step needed
crewhaus run cli.yaml # interactive terminal
crewhaus run browser.yaml --prompt "research X" # one-shot browser session
The browser target launches a headless Chromium via Playwright — run bunx playwright install chromium once if you don't already have it. The compiled bundle and crewhaus run use the same runtime; pick whichever fits your deployment.
Same agent. Different runtimes. Only target: changed.
Example: tools and richer shapes
The example above needs no tools. Most real agents do — and tools come from two places. Built-in tools go in a tools: list (read, write, edit, bash, grep, webFetch, webSearch, …). MCP server tools are auto-discovered: declare the server under mcp_servers: and every tool it exposes is registered for you — you never list them by hand.
# triage.yaml — a CLI agent backed by a GitHub MCP server
name: github-issue-triage
target: cli
agent:
model: claude-sonnet-5
instructions: |
You triage GitHub issues by reading them and assigning labels.
mcp_servers:
github:
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_TOKEN
Richer shapes keep that same agent: (and mcp_servers:) block and layer their own config on top — only target: and the shape-specific block change. The same triage agent becomes a Slack bot, or an eval graded against a labeled dataset:
# slack.yaml — same agent, dispatched as a Slack bot
name: github-issue-triage
target: channel
agent:
model: claude-sonnet-5
instructions: |
You triage GitHub issues by reading them and assigning labels.
mcp_servers:
github:
transport: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_TOKEN
channels:
slack:
botToken: $SLACK_BOT_TOKEN
signingSecret: $SLACK_SIGNING_SECRET
routing:
sessionKey: thread
# eval.yaml — same agent, graded against a labeled dataset
name: github-issue-triage
target: eval
agent:
model: claude-sonnet-5
instructions: |
You triage GitHub issues by reading them and assigning labels.
dataset:
name: triage-cases
version: v1
split: dev
graders:
- name: exact_match
concurrency: 4
Other shapes follow the same rule — retrieve: + indexing: for a RAG pipeline, queue: for a batch worker, voice: for a realtime agent — but the agent: block stays identical across all of them.
Memory & continuity (v0.3.0)
Every agent-loop harness now remembers:
Continuity, on by default — persistent focus, plans, and goals with a claimed→proven proof ladder, a verbatim requirements ledger that survives compaction, and a deterministic handoff.md at teardown. One line — continuity: false — restores the 0.2.x bundle byte-for-byte.
A local wiki — memory.wiki is versioned, update-in-place semantic memory with hybrid recall; memory.dream consolidates it on a schedule (deterministic pass + budget-capped model pass).
One-knob hosted memory — thredz: true flips the wiki to a hosted Thredz backend: one env var, private by default, and a Thredz outage degrades the run instead of killing it.
Self-teaching harnesses — a learning: block wires the shipped learning-loop skill: recall-then-answer with citations, gap-driven study, reflection, and a first-class /exam.
Honest failures — an out-of-funding run says so, with a fix line and a meaningful exit code, instead of "agent exited."
The proof is the self-teaching-expert demo, whose ~150-line mechanism prompt shrank to two knobs plus domain content:
The compiler, runtime, eval stack, and security fabric live in this repo. Tooling that sits around the compiler — Studio, IDE extensions, the browser playground — lives in crewhaus/utilities, and the section-* example specs live in crewhaus/demos. Both consume factory via tsconfig path aliases.
Section example specs — demos/smoke holds the per-section reference specs (section-15-smoke, section-33-discord-smoke, etc.) used to drive integration runs.
Crewhaus Forge
Community registry for shared harnesses, skills, tools, and recipes. Coming Summer 2026.See what's coming →
Contributing
Contributions are welcome. CrewHaus is async-first and BDFL-lite — see GOVERNANCE.md for how decisions are made and CONTRIBUTING.md for how to contribute.
Vulnerability reports go to a private channel, not GitHub Issues. See SECURITY.md.
License
Apache License 2.0. The Apache-2.0 license covers the code. CrewHaus, Crewhaus Factory, Crewhaus Cloud, Crewhaus Forge, and the logo are trademarks; see TRADEMARK.md for use-of-marks policy.