BuildYourOwnHarness

[English](README.md) | [한국어](./docs/i18n/ko/README.md) | [日本語](./docs/i18n/ja/README.md) | [简体中文](./docs/i18n/zh-Hans/README.md) | [Español](./docs/i18n/es/README.md) | [Deutsch](./docs/i18n/de/README.md) | [Français](./docs/i18n/fr/README.md) | [Português](./docs/i18n/pt/README.md) | [Русский](./docs/i18n/ru/README.md) | [العربية](./docs/i18n/ar/README.md)

BuildYourOwnHarness (BYOH)

Your AI agent, built around you

Not a generic template — a harness compiled from your role, expertise, and goals.

Most AI setups hand you a fixed set of tools and say "good luck." BYOH flips that: it interviews you, learns what you actually do, and generates a personalized agent harness — skills, agents, goal pipelines — that fits your workflow out of the box.

Who is this for?

• Developers who want an agent that already knows their stack, test style, and delivery cadence
• Researchers who need literature review, citation tracking, and synthesis wired together
• Creators who want a writing partner that matches their voice and project structure
• Business analysts who need decision frameworks and reporting pipelines, not raw chat

If you've ever thought "I wish my AI actually knew my context" — this is what BYOH does.

How it works in 60 seconds

BYOH is built to be driven by your AI agent — not by you typing commands. Install the plugin, then just talk. The conversation is the interview, the wizard, and the build.

1. Install the plugin      # Claude Code / Codex / agy — auto-installs the binary
2. "Build me a harness"    # your agent interviews you, builds, fills any gaps
                           # itself, and installs — all in conversation

On the next session your host loads the harness automatically — agents, skills, and goal pipelines tuned to you.

Install the plugin (recommended)

Using Claude Code, Codex, or agy? Install the plugin. It bundles the MCP server and auto-installs the binary on first load — no Rust toolchain, no manual setup:

Claude Code:

claude plugin marketplace add epicsagas/BuildYourOwnHarness
claude plugin install byoh@epicsagas

agy (Antigravity):

agy plugin install /path/to/BuildYourOwnHarness
agy plugin enable byoh

Codex:

codex plugin marketplace add /path/to/BuildYourOwnHarness
codex plugin add byoh@epicsagas

Using any other MCP-compatible host?

BYOH speaks MCP, so Cursor, Zed, Continue, and friends work too. Install the [binary](#install-the-binary-directly) once, then point your host at the server:

byoh serve   # stdio MCP server

{ "mcpServers": { "byoh": { "command": "byoh", "args": ["serve"] } } }

> Note: The repo is currently private. Use the paths above. Once public it will appear in the shared epicsagas/plugins marketplace.

Install the binary directly

Only needed if you're not using the plugin (the plugin auto-installs the binary on first session) or you want BYOH on a non-plugin MCP host. Prebuilt binaries are published for every release — no Rust toolchain required.

macOS / Linux

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/BuildYourOwnHarness/releases/latest/download/install.sh | sh

Windows (PowerShell)

irm https://github.com/epicsagas/BuildYourOwnHarness/releases/latest/download/install.ps1 | iex

From source

cargo install byoh --git https://github.com/epicsagas/BuildYourOwnHarness

byoh --version   # verify

Agent-led mode — the main path

Once your host is connected, you don't type commands — you just talk. Your agent calls BYOH's MCP tools directly, and the conversation is the interview, the build, and the evolve cycle:

> You: I'm a backend Go developer shipping a payments API this month. Build me a harness. > > Agent: (scans your repo via profile_scan, asks a few targeted questions via profile_interview, locks the genre to developer) → build synthesizes a HarnessBundle and classifies every skill as matched / authored / skeleton → for any skeleton the profile needs (say, a payments-specific verification skill), the agent authors it on the spot via author_skill, then builds again to confirm → installs agents, skills, and a secure-ship goal pipeline into Claude Code. Authored content persists across rebuilds. Done — next session, your agent already speaks your stack.

That same flow, in the suggested tool order:

profile_create → profile_scan → profile_interview → profile_confirm
           → build → (author_skill / author_doc to fill skeletons) → build → install_plugin

build synthesizes the bundle (compile + preset injection + static gate) and classifies every skill as matched (real preset body), authored (filled by you via author_skill), or skeleton (genre-template placeholder) — the agent reads that to decide whether to install now, author the skeletons, or iterate the profile first. author_skill / author_doc write to a profile overlay that build reads back, so authored content survives every rebuild.

Available tools: profile_read, profile_create, profile_scan, profile_interview, profile_confirm, build, author_skill, author_doc, enable_hook, list_overrides, delete_override, render_plugin, install_plugin, catalog_search, catalog_vendor.

Want the agent to walk you through it? Just say "build my harness" — the bundled byoh-guide agent orchestrates the whole flow.

Plugin catalog

The catalog is built from the quemsah/awesome-claude-plugins README — a community-maintained, star-ranked list of the top 100 Claude plugin repositories. BYOH ships a prebuilt bundle (rebuilt weekly, every Monday 03:17 UTC) so byoh catalog index resolves in seconds; pass --no-bundle to parse the upstream list directly.

# One-time index — downloads a prebuilt bundle in seconds
byoh catalog index

# Search offline — no network needed after indexing
byoh catalog search "memory" --genre developer --limit 5

# Add a plugin to your harness
# license, keywords, and genre are auto-detected from the cloned repo
byoh catalog vendor obra/superpowers --genre developer

The LLM agent (via catalog_search / catalog_vendor MCP tools) can do this entire flow autonomously — "add a memory plugin to my harness" — or you can drive it directly from the CLI.

A few companion tools are seeded into search results as reference material (not dependencies): BYOH's own execution-layer tools — alcove (doc server), obsidian-forge (vault automation), epic-harness (hook/skill runtime) — surface contextually (a "doc server" / "search backend" query finds alcove) so an agent can recommend them when relevant. Vendor one only if you actually want it; bundles ship dependency-free either way.

Example harnesses

Two harnesses built with the flow above and published to GitHub — each a multi-host polyglot plugin (Claude Code · Codex · Antigravity), made of skills, manifests, and (where matched) agents only, so it runs on any machine with no extra binaries:

• byoh-paper-whisperer — researcher genre · 13 skills · 1 agent. Survey, read, analyze, and take notes on AI/ML papers. The bundled Research Analyst agent tags every claim with an evidence tier (primary > peer-reviewed > secondary > anecdotal) and never overstates a source; a search_citations MCP tool wires citation checks to a knowledge base (alcove).
• byoh-market-gtm-analyst — business genre · 9 skills. Scopes a market/competitive research engagement (goal), runs evidence-tiered market and competitor analysis (analyze), builds a positioning read (decide), and produces a GTM strategy doc with per-channel ROI and a risk register (execute / roi_evaluation / risk_assessment) — all gated by the same Critic / Seesaw / Stagnation safety gates.

# install byoh-paper-whisperer into Claude Code
claude plugin marketplace add epicsagas/byoh-paper-whisperer
claude plugin install byoh-paper-whisperer@byoh-paper-whisperer

Each repo's README carries per-host install steps for Codex and Antigravity too.

Power users: the CLI (optional)

Every flow above is also reachable from the terminal. The CLI is auxiliary — useful for scripting, CI, or when you'd rather not chat — but the agent-led path is the intended one.

Your first harness — from the CLI

byoh profile init me --paths ./src ./docs   # auto-scans your project
byoh profile confirm me --genre developer   # lock in your genre (+ optional --goal)

byoh render me --target claude              # synthesize (compile + preset injection + static gate) and write the HarnessBundle; or: codex | agy | all (default: all)
byoh install me --scope local               # render to dist/, activate into this project's .claude/ only
byoh install me --scope global              # ...or ~/.claude + ~/.codex + ~/.gemini (was --host)
byoh install me --scope publish             # ...or add LICENSE + .gitignore and print git instructions

The interview itself is agent-led (the profile_interview MCP tool) — the conversation is the interview, so there is no interactive CLI interview. The build's static gate (Critic / Seesaw / Stagnation safety-gate presence, MCP schema, hook input) always runs and can never be bypassed — so the bundle is structurally valid before it ships. Post-install improvement is a conversational retrospective in later sessions, not a tool call.

How it works under the hood

BYOH's synthesis engine matches your profile tags against the skill registry, orders them into a dependency-resolved pipeline, and emits a HarnessBundle — a git-ready artifact that renders into the native format of any supported host. Skills the registry doesn't cover stay as skeletons; the agent fills them via author_skill, writing to a profile-scoped overlay that the next build reads back — so authored content persists and the static gate still runs on every build.

• 4-ring security model — lifecycle spec (Ring 0) and built-in pipeline skills (Ring 1) through community/untrusted skills (Ring 3), each with escalating validation; vendored skills are sha256-pinned and verified at read + embed time
• 3-gate safety floor — every build's static gate confirms Critic (quality), Seesaw (regression), and Stagnation (plateau) gates are present; no bypass
• Goal-oriented pipelines — declaring a 30-day goal (product launch, research report, secure ship…) overlays a matching skill ladder automatically

Architecture: hexagonal — domain / ports / adapters / application / compiler / evolve / templates / deploy / catalog / mcp / i18n / security / cli. See AGENTS.md for the full guide.

Full CLI reference

The CLI is intentionally small: machine entry points (serve, catalog index in CI, vendor for maintainers) plus a scriptable mirror of the core build flow. Interview and evolution are MCP-only (agent-led).

# Profile
byoh profile init  [--paths ...]      # non-destructive project scan
byoh profile confirm  --genre  [--goal ]  # confirm and lock profile
byoh profile show                     # print the profile YAML

# Build (static gate always runs; render synthesizes: compile + preset injection)
byoh render  [--target ]        # claude | codex | agy | all (default: all); writes the HarnessBundle
byoh install  [--target ] [--scope local|global|publish] [--host] [--force]  # dist/ tree; --scope decides where it goes (local=this project, global=HOME, publish=+LICENSE/.gitignore+git steps). --host is legacy for --scope global.

# Community skills (maintainer/build-time; sha256-pinned and verified at read + embed time)
byoh vendor add  --genre  --id  [--keywords k1,k2] [--trust] [--sha ]
byoh vendor list
byoh vendor remove  --genre 

# Catalog
byoh catalog index [--no-bundle] [--limit N]
byoh catalog search "" [--genre ] [--tags k1,k2] [--limit N]
byoh catalog vendor  [--genre ] [--keywords k1,k2]

# Diagnostics / server
byoh doctor                                 # check execution-layer tools
byoh serve                                  # stdio MCP server (agent-led mode)

Profiles and the catalog cache live under ~/.byoh by default (override with BYOH_HOME).

Build & develop

cargo build --release
cargo clippy --all-targets -- -D warnings
cargo test                        # unit + e2e
cvp                               # parallel: check → clippy → test → fmt → build

The mcp feature (stdio MCP server) is on by default. BYOH ships no embedded knowledge base — for retrieval, point your generated harness at a doc server like alcove.

Acknowledgments

BYOH stands on the shoulders of several community efforts:

• Plugin catalog — sourced from quemsah/awesome-claude-plugins, a star-ranked community list of the top 100 Claude plugin repositories. Without it, the catalog would not exist.
• Companion tools — designed to interoperate with alcove (doc server / RAG), Episteme (knowledge graph), and obsidian-forge (vault automation).
• Open-source stack — built on clap, serde, ureq, and the Rust ecosystem.

Catalog entries and vendored community skills keep their own licenses (detected automatically at vendor time). BYOH itself is Apache-2.0.

License

Apache-2.0.

Source & license

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

• Author: epicsagas
• Source: epicsagas/BuildYourOwnHarness
• License: Apache-2.0
• Homepage: https://github.com/epicsagas/BuildYourOwnHarness

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