agent-bus-plugins
MustaphaSteph/agent-bus-plugins
Codex and Claude Code plugins for agent-bus: local message bus for AI agent-to-agent communication. Bundles the MCP server, slash commands, and the universal Agent Skill.
Instalação
npx convez-ai MustaphaSteph/agent-bus-plugins1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
agent-bus plugins
Codex and Claude Code plugins that bundle:
- The agent-bus MCP server (
@agent-bus-connect/cli) — 65 tools plus CLI/UI views for agent-to-agent messaging, the localagent-bus uiweb cockpit, async asks, truncation-safe inbox previews, exact message fetches, team-scoped send/ask/delegation/boards, roster cleanup, team chat, activity timelines, cockpit dashboards, visible current-work updates, workflow Kanban, tasks, task progress events, result bundles, cancellation, channels, capability routing, status boards, acknowledgements, review gates, handoffs, scope checks, decisions, memories, session briefs, and final reports. - The universal
agent-busAgent Skill — natural-language coordinator playbook ("ask the reviewer", "delegate this", "get a second opinion", "put worker-2 to sleep", "final merge report") that translates intent into tool calls without users naming tools or parameters. - Optional Stop hook for listener resilience (Claude Code: on by default; Codex: opt-in).
Source code for the bus itself lives at https://github.com/MustaphaSteph/agent-bus.
Install Order
Install the npm CLI first, then install the plugin. The plugin declares
the MCP server command, but the @agent-bus-connect/cli package
provides the actual agent-bus-mcp binary. Installing the plugin before
the CLI can produce an ENOENT MCP startup error because Claude Code or
Codex cannot find agent-bus-mcp.
1. Install the bus binary once per machine
npm i -g @agent-bus-connect/cli@latest
which agent-bus-mcp
agent-bus --version
That puts agent-bus (CLI) and agent-bus-mcp (MCP stdio server) on your PATH. Plugins below verify both are available through the bundled setup checker. They do not silently install npm packages; run the checker or installer with --install-cli when you want it to fix a missing or old CLI.
2. Choose your host plugin/skill install
Codex (CLI + Desktop)
Step 1 — add the marketplace:
codex plugin marketplace add MustaphaSteph/agent-bus-plugins
The Codex marketplace lives at the repo root (.agents/plugins/marketplace.json), so no --sparse flag needed.
Step 2 — install the agent-bus plugin from Codex's plugin UI (in Codex CLI's interactive mode or Codex Desktop's plugin panel). Current Codex CLI builds expose only codex plugin marketplace add/upgrade/remove from the shell — the actual install action happens inside the agent UI. Once a future Codex CLI build ships a codex plugin install <name> subcommand, this step will also be runnable from a script.
Hooks note: the listener-resume Stop hook ships disabled by default. To opt in, edit ~/.codex/config.toml:
[features]
plugin_hooks = true
Then re-install or reload the plugin. Without the hook, listener mode still works via the long-blocking inbox(wait_s=110) call alone — the hook is purely a recovery path for sessions that fall out of the loop.
Cursor / Gemini CLI / Goose / OpenCode / Junie / Amp / Kiro / others
If your tool supports the open Agent Skills format but doesn't have a plugin marketplace, use the universal installer:
curl -fsSL https://raw.githubusercontent.com/MustaphaSteph/agent-bus-plugins/main/install.sh | sh
It auto-detects every supported tool's config directory under $HOME and drops the canonical agent-bus skill into each one's skills/ folder. Then prints the per-tool MCP-server registration hints so you can finish wiring up the bus.
Options:
./install.sh --dry-run # show plan, change nothing
./install.sh --target ~/.cursor/skills # force a specific destination
./install.sh --install-cli # also install/upgrade the npm CLI
The skill needs the bus binary too. Install once with
npm i -g @agent-bus-connect/cli@latest, or pass --install-cli to
this installer.
Claude Code
/plugin
> Marketplaces
> Add MustaphaSteph/agent-bus-plugins
> Install agent-bus
The marketplace manifest lives at .claude-plugin/marketplace.json at the repo root, so the bare owner/repo form works without flags.
The plugin includes:
- The agent-bus MCP server config (the actual
agent-bus-mcpbinary comes from the CLI package installed in step 1) - The
agent-busskill (cross-tool coordinator playbook) /main <name>slash command — primes a coordinator session to talk to the bus in natural language/listen <name>slash command — turns a session into a passive helper that responds when called- Always-on Stop hook for listener resilience (Claude Code doesn't gate plugin hooks the way Codex does)
Verify
After install, in any new session:
List the agent-bus MCP tools and call whois.
You should see all 65 tools and (if no agents are registered yet) an empty agent list.
If something's off, run the skill's setup checker:
~/.claude/skills/agent-bus/scripts/check-setup.sh # Claude Code
~/.codex/skills/agent-bus/scripts/check-setup.sh # Codex
That validates Node ≥ 20, agent-bus-mcp on PATH, and that the installed CLI version satisfies the skill's requires field.
To install/upgrade the CLI from the checker explicitly:
~/.claude/skills/agent-bus/scripts/check-setup.sh --install-cli
~/.codex/skills/agent-bus/scripts/check-setup.sh --install-cli
Repo layout
.
├── .agents/plugins/marketplace.json ← Codex marketplace at root
├── plugins/agent-bus/ ← Codex plugin body
│ ├── .codex-plugin/plugin.json
│ ├── .mcp.json (command: agent-bus-mcp)
│ ├── hooks/hooks.json (disabled by default)
│ └── skills/agent-bus/ (vendored from main repo)
├── .claude-plugin/marketplace.json ← Claude Code marketplace at root
├── claude-code/plugins/agent-bus/ ← Claude Code plugin body
│ ├── .claude-plugin/plugin.json
│ ├── commands/{main,listen}.md
│ ├── hooks/hooks.json
│ ├── hooks-handlers/stop-hook.sh
│ └── skills/agent-bus/ (vendored, same content as Codex copy)
├── install.sh ← universal fallback for skills-aware tools
├── scripts/sync-skill.sh ← vendors skill into BOTH plugin paths
├── .sync-version ← what tag/commit the vendored skill came from
└── package.json
Versioning
The skill is vendored, not git-submoduled. Single canonical copy lives in the main agent-bus repo at the ref listed in .sync-version. CI fails any PR that ships a vendored copy that drifts from the pinned ref.
Bumping the skill means:
- Update + commit the skill in the main repo.
- In this repo, bump the pinned ref in
scripts/sync-skill.shwhen needed. - Run
npm run sync-skill. - Commit the regenerated
plugins/agent-bus/skills/agent-bus/and.sync-version. - Push.
For local dev iteration without tagging, use npm run sync-skill:dev (reads from ../agent-bus/).
Troubleshooting
| Symptom | Fix |
|---|---|
ENOENT or agent-bus-mcp: command not found after plugin install | Run npm i -g @agent-bus-connect/cli@latest, verify which agent-bus-mcp, then reconnect /mcp or restart the host app. The plugin declares the MCP command, but the npm package provides the actual binary. |
| Setup checker says CLI is missing or old | Run <skills-dir>/agent-bus/scripts/check-setup.sh --install-cli to install/upgrade via npm. |
Setup checker still says agent-bus X is older than required Y after installing latest | The plugin/skill is ahead of the published npm CLI. Check npm view @agent-bus-connect/cli version; publish the required CLI version first, or lower MIN_AGENT_BUS to the latest published version before releasing the plugin. |
| Skill installed but tools not visible | Open a NEW session — Claude Code / Codex read MCP config at session start. |
| Codex Stop hook doesn't trigger | Check [features].plugin_hooks = true in ~/.codex/config.toml and reload the plugin. Without that flag, plugin-bundled hooks are inert in Codex. |
| Setup check exit non-zero | Read the printed install hint; the script's exit message tells you exactly what's missing. |
License
MIT.