erbina

A Claude-Code-only MCP server that bootstraps your dev environment from one prompt — install, wire, and verify CLI tools and other MCP servers from curated recipes, and see where every MCP server lives across your scopes.

Named after the Lusitanian goddess of boundaries and crossings — erbina is the threshold a tool crosses to become part of your environment. Sibling to ataegina (goddess of rebirth), which is also erbina's proof-of-concept recipe #1.

The recipe contract is the core idea. One server, eleven tools, and a curated set of recipes spanning cli-tools, scope-wiring mcp-servers, and profiles that bundle them (see the Recipe gallery). Each is one YAML file held to a conformance bar — schema + linter policy + a 100%-covered offline suite, plus a weekly job that actually installs it on macOS, Linux, and Windows — and adding one is the point.

Why this exists

Setting up a coding-agent environment is death by a thousand cuts: you install a CLI, hand-edit a config, add an MCP server — then find out it's in the wrong scope and isn't showing up. Claude Code spreads MCP config across up to four files in two apps, with no single place that knows what's installed where (anthropics/claude-code#27458, #8288, #5963).

erbina makes setup a thing an agent does for you, and proves worked:

• It's an MCP server, so an agent must drive it. There is no human entry point — run it by hand and you get nothing. Nobody mistakes it for a manual installer that "should just work."
• Recipes, not one-shot installs. Each entry is a contract: detect → install → configure → verify. Idempotent by construction — it detects what's already there and skips it, and success means the tool runs, not that a line was written to a file. Recipes also compose (requires: prerequisites, profiles that bundle a whole set) and cover the full lifecycle: update → re-verify → rollback, uninstall, and a doctor health-check over everything erbina installed.
• Scope-aware. It knows about Claude Code's local / project / user scopes, wires MCP-server recipes into the right one, and audits all three so you finally have one place that answers "what's installed, and where?"
• Proven, not just written. On top of the offline suite, a weekly (and on-demand) CI job bootstraps recipes for real against live package managers on macOS, Linux, and Windows — so a renamed brew formula, a dead URL, or a bad winget id is caught, not shipped.

Install

erbina is a single Python file run by uv (it declares its own dependencies inline — no venv to manage).

git clone https://github.com/noahhyden/erbina
# register it with Claude Code (use --scope user to make it available everywhere)
claude mcp add erbina --scope user -- uv run --script /absolute/path/to/erbina/server.py

Then, in Claude Code, just ask: "use erbina to set up ataegina" — the agent inspects the recipe, shows you exactly what it will run, then bootstraps and verifies it.

Requirements: uv and Claude Code, on macOS, Linux, or Windows. Plus whatever a recipe's install method needs — typically brew on macOS, winget on Windows, or a language toolchain (cargo / go / pipx) or curl fallback elsewhere. Every method is guarded, so only one that actually exists on your machine ever runs.

Tools

The server's instructions tell the agent to always inspect (or dry-run) and show you the commands before executing — erbina shells out to package managers with real privileges (it runs as a sibling process, not under Claude Code's Bash sandbox), so consent before execution is the safety model.

How a recipe works

A recipe is four phases an agent executes. The proof-of-concept entry, recipes/ataegina.yaml:

detect:   { command: "ataegina --version", expect_exit: 0 }   # skip install if present
install:                                                       # first guard to pass wins
  methods:
    - { id: homebrew, when: "command -v brew", run: "brew install noahhyden/tap/ataegina" }
    - { id: curl,     when: "command -v curl", run: "curl -fsSL .../install.sh | sh" }
configure: { steps: [ { run: "ataegina init --yes", needs_project_dir: true, optional: true } ] }
verify:   [ { command: "ataegina --version", expect_exit: 0 } ]

A kind: mcp-server recipe instead wires a server into a chosen scope — its configure step is claude mcp add <name> --scope ${scope} -- …, where ${scope} is substituted from the scope you pass to bootstrap. See recipes/fetch.yaml. A kind: profile recipe installs nothing itself — it just requires: a curated set, so one prompt bootstraps the whole bundle.

Recipes can also declare optional blocks: requires: (prerequisites bootstrapped first), version: + update: / rollback: (auto-updates, with latest: as a command or the { github: owner/repo } shorthand), and uninstall: (teardown). Because each install method's when: guard runs in the host shell, methods are cross-platform — a winget method fires only on Windows, brew/cargo/curl only where they apply. The full schema is in SCHEMA.md.

Auto-updating tools

A recipe can opt into update checks by declaring a version: block (an installed current command and a latest source) and, optionally, update: / rollback: methods. Then:

• check_updates compares installed vs latest (numeric/pre-release aware, via packaging) and reports what's out of date — it never claims an update it can't parse, skips pinned tools, and for a { github: … } source includes a release-notes link so you can review before applying.
• update applies the upgrade and re-runs verify; if verify fails it rolls back to the recorded previous version (when the recipe declares a rollback: command) or marks the tool broken and returns a plan.
• erbina records what it manages in a small state manifest (~/.erbina/state.json) — versions, install method, and pins.

Checks are agent-driven; you can also enable an opt-in SessionStart hook or a /schedule routine so the agent checks for you and asks before applying anything. See AUTO_UPDATE.md for the design, the version:/update:/ rollback: schema, and the trigger setup.

Recipe gallery

The curated registry today. Each links to its YAML; cli-tools install a binary, mcp-servers wire a server into a chosen Claude Code scope, and profiles bundle several recipes. (This list is kept in sync with recipes/ by a test.)

CLI tools

• ataegina — collision-free dev environments per git worktree
• bat — a cat clone with syntax highlighting and Git integration
• bottom — a cross-platform graphical process/system monitor
• delta — a syntax-highlighting pager for git, diff, and grep output
• difftastic — a structural (syntax-aware) diff tool
• dust — a more intuitive version of du
• eza — a modern, maintained replacement for ls
• fd — a fast, friendly alternative to find
• gh — GitHub's official command-line tool
• httpie — a human-friendly command-line HTTP client
• hyperfine — a command-line benchmarking tool
• jq — command-line JSON processor
• lazygit — a simple terminal UI for git commands
• procs — a modern replacement for ps
• ripgrep — blazing-fast recursive search
• sd — intuitive find & replace (a friendlier sed)
• tealdeer — a very fast tldr client (simplified man pages)
• tokei — count your code, quickly
• uv — an extremely fast Python package and project manager
• yq — a portable command-line YAML/JSON/XML processor
• zoxide — a smarter cd command that learns your habits

Profiles (bundle several recipes; bootstrap resolves them all)

• modern-unix — a curated set of modern CLI replacements (ripgrep, fd, bat, eza, dust, zoxide)

MCP servers

• everything — official MCP reference/test server exercising the full protocol
• fetch — official MCP server for retrieving web content
• git — official MCP server for Git repository operations
• memory — official MCP server for a persistent knowledge graph
• sequentialthinking — official MCP server for structured step-by-step reasoning
• time — official MCP server for time & timezone conversions

Adding a recipe

Drop a <id>.yaml in recipes/ following SCHEMA.md. kind: cli-tool installs a binary; kind: mcp-server additionally wires it into the chosen Claude Code scope; kind: profile just bundles others via requires:. Keep detect cheap and verify honest (prove it runs).

What this is not

Not a package manager you run by hand (that's mcpm / brew / aqua), not a discovery registry (that's Smithery), and not a way to "rebuild my laptop deterministically" (use Nix / chezmoi / a Brewfile — an LLM-driven setup is the wrong tool for reproducible provisioning). erbina's niche is the unclaimed intersection: agent-run, verify-on-install recipes that span CLI tools and MCP servers, aware of Claude Code's scopes.

Safety model

erbina runs as an ordinary sibling process of Claude Code — not inside its Bash sandbox — so a recipe's commands execute with your real privileges. The safety model is consent before execution: inspect_recipe and bootstrap(dry_run=true) show you the exact commands first, and the server instructs the agent to surface that plan before any real run. Only bootstrap recipes you've read. See SECURITY.md for the full trust model and how to report a vulnerability.

Contributing

The most useful contribution is usually a new recipe — one YAML file in recipes/. See CONTRIBUTING.md for the ground rules and how to smoke-test with an in-memory FastMCP client, SCHEMA.md for the recipe contract, and CHANGELOG.md for what's landed. By participating you agree to the Code of Conduct.

License

MIT. See LICENSE.