@guildex.net/install

One-command installer for Guildex AI workers.

npx @guildex.net/install <worker-id> [--target <name>]

<worker-id> is the slug from the Guildex marketplace (e.g., mason-grey, sloane-reyes). The install pulls the worker's DAP YAML from https://guildex.net and compiles it for your local runtime.

Targets

• openclaw (default) — installs into ~/.openclaw/agents/guildex-<id>/ and wires the worker into your OpenClaw runtime as a dispatchable agent. Includes a full dispatcher scaffold by default (see "Default install" below).
• claude-code — installs into ~/.claude/agents/guildex-<id>.md. Use --scope project to install into <cwd>/.claude/agents/ instead.

Default install (greenfield OpenClaw)

npx @guildex.net/install mason-grey --target openclaw

Drops:

1. ~/.openclaw/agents/guildex-mason-grey/ — worker workspace, AGENTS.md, INSTALL_LOG.json, etc.
2. ~/.openclaw/workspace/HEARTBEAT.md + taskboard.md — main's dispatcher operating manual (when to dispatch, how to verify completion, Telegram routing rules).
3. ~/.openclaw/workspace/scripts/notify-main.sh — one-line wrapper workers use to event-trigger main on completion.
4. ~/.openclaw/workspace/scripts/set-main-cadence.sh — adaptive cadence helper (5min active / 4h idle).
5. A cron entry in ~/.openclaw/cron/jobs.json named Guildex main Heartbeat — main wakes every 5 minutes to check the taskboard.
6. Telegram chat_id auto-discovery from ~/.openclaw/agents/main/sessions/sessions.json — main's HEARTBEAT.md and notify-main.sh get templated with the real chat_id.

Every file is marker-gated (<!-- guildex-heartbeat:v1 --> etc.). On re-install we overwrite only files bearing our marker; pre-existing user content is preserved byte-identical. On the last-worker uninstall we remove all of the above.

BYOC: Bring Your Own CEO (--workers-only)

If you already run your own OpenClaw dispatcher — for example, openclaw-company-os, a hand-rolled CEO + cron heartbeat, or any custom main/AGENTS.md scaffold — passing --workers-only installs just the worker and leaves your dispatcher untouched.

npx @guildex.net/install mason-grey --target openclaw --workers-only

What --workers-only does:

• Installs the worker DAP, workspace, INSTALL_LOG.json normally.
• Sets the worker's own tools.alsoAllow so it can receive sessions_send.
• Adds the worker's agent id to the global tools.agentToAgent.allow (so your CEO can dispatch to it) and flips tools.agentToAgent.enabled = true if it isn't already.
• Writes ~/.openclaw/workspace/guildex-roster.md — a copy-paste-ready snippet listing every installed Guildex worker, the exact sessions_send call to invoke each, and how to wire your own event-trigger wrapper.

What --workers-only does NOT do:

• Does not write ~/.openclaw/workspace/HEARTBEAT.md, taskboard.md, scripts/notify-main.sh, or scripts/set-main-cadence.sh.
• Does not add the Guildex main Heartbeat cron entry.
• Does not modify main's tools.alsoAllow.
• Does not modify main's AGENTS.md.

Wiring instructions: open ~/.openclaw/workspace/guildex-roster.md and copy whichever sections fit. Typical patterns:

• Paste the ### <Worker> — \`` blocks into your own CEO's HEARTBEAT.md so it knows which specialists exist.
• For event-trigger push (workers waking your CEO on completion), wire your own wrapper that targets your CEO's sessionKey. The roster snippet documents the message format Guildex workers emit.

--setup-dispatcher-only

If you want to verify Guildex's dispatcher pipeline before installing any workers:

npx @guildex.net/install --setup-dispatcher-only --target openclaw

Drops just the main scaffold + cron heartbeat. No worker DAP. Useful for first-time OpenClaw users who want to confirm Telegram chat_id discovery, cron firing, and main's behavior end-to-end before committing to a specific worker.

Auto-detect warning

On any install (default or --workers-only), Guildex scans ~/.openclaw/cron/jobs.json for cron entries that look like your own dispatcher (non-Guildex cron on main, or fast cron entries on any non-main agent). If detected and you're using the default install, you'll see:

WARN: Detected pre-existing OpenClaw cron entries that look like your own dispatcher:
  - agentId=main name="My Company OS Heartbeat" everyMs=600000
Guildex's default install will add its own main heartbeat scaffold + cron, which may conflict with yours.
If you want Guildex to leave your dispatcher alone and only add the workers, re-run with:
  npx @guildex.net/install mason-grey --target openclaw --workers-only
Proceeding with the default install for now.

Guildex's scaffold files are all marker-gated, so the default install will preserve any hand-written HEARTBEAT.md / taskboard.md / scripts you already authored. The warning is a heads-up that if your dispatcher is working, you probably want --workers-only instead.

Uninstall

npx @guildex.net/install <worker-id> --target openclaw --uninstall

Reverses every action recorded in the worker's INSTALL_LOG.json: removes the worker dir, drops it from tools.agentToAgent.allow, removes any messaging tools we added to main's tools.alsoAllow (set-difference — user-added entries preserved), excises our fenced block from main's AGENTS.md, and on the last-worker uninstall removes the main scaffold + cron heartbeat + roster snippet (all marker-gated).

Non-invasive contract

• All Guildex files are namespaced under guildex-<id> or carry a Guildex marker.
• For openclaw: openclaw.json is touched only via openclaw config set/unset — never direct JSON patching.
• For claude-code: only <root>/.claude/agents/guildex-<id>.{md,INSTALL_LOG.json} is written. settings.json is never touched (Claude Code auto-discovers).
• Pre-existing user files without a Guildex marker are preserved byte-identical.
• Allowlists are set-union on install, set-difference on uninstall.

claude-code auto-wire of required MCP servers (Sprint 17.C)

For --target claude-code, every DAP tool marked required: true that maps to a known MCP server is wired automatically as part of install. Instead of printing a claude mcp add ... instruction for the user to run, the installer shells out to the supported claude mcp add CLI itself so the freshly-hired worker is immediately functional.

What auto-wire does:

• For each required: true tool with a known MCP server: runs claude mcp add <name> --scope <agent_scope> -- <command> <args...>. Uses the agent's install scope (user or project) for the MCP scope so an agent installed at --scope project gets project-scoped MCPs.
• For the filesystem MCP specifically: the allowlisted directory defaults silently to ~/guildex-workspace. The directory is auto-mkdir -p'd at install time so the worker can read and write immediately, with zero prompts.
• For required: true tools with kind: "shell": skipped (Claude Code's built-in Bash tool already covers them; no MCP needed).
• For required: false tools (OAuth-bearing things like GA4, GSC, Slack, ads platforms): NOT auto-wired. They're surfaced as "Optional integrations you can enable later" in the install output.

Failure handling (graceful, never aborts install):

• claude CLI not on PATH → no shell-out attempted; the install falls through to printing the legacy manual hint list under a "claude CLI not detected; complete these steps manually:" header.
• claude mcp add returns non-zero → stderr is logged, that single MCP falls back to a manual hint; other MCPs in the same install continue normally.

Uninstall (reference-counted):

• Each install records the MCP names it relies on in its INSTALL_LOG.json under auto_added_mcps. Both freshly-added MCPs and MCPs already present at install time (shared across workers) are tracked.
• On uninstall, the installer scans every sibling guildex-*.INSTALL_LOG.json in the same scope. An MCP is claude mcp remove-d ONLY when no other Guildex agent still references it. Otherwise it's left in place with a "Kept MCP server X (other Guildex agents still use it)" log line.
• User-added MCPs — anything whose name doesn't appear in any Guildex INSTALL_LOG.json's auto_added_mcps — are never touched by uninstall. If you ran claude mcp add for a server yourself, it stays where you put it.

Source

https://github.com/Guildex/guildex