convez.ai
MCP Server
MustaphaSteph

agent-bus-plugins

MustaphaSteph/agent-bus-plugins

Ver no GitHub
InicialPluginScore · de 0 a 100

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-plugins

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 semanas
Versão
v0.41.0
Issues abertas
0
Contribuidores
1

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 local agent-bus ui web 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-bus Agent 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-mcp binary comes from the CLI package installed in step 1)
  • The agent-bus skill (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:

  1. Update + commit the skill in the main repo.
  2. In this repo, bump the pinned ref in scripts/sync-skill.sh when needed.
  3. Run npm run sync-skill.
  4. Commit the regenerated plugins/agent-bus/skills/agent-bus/ and .sync-version.
  5. Push.

For local dev iteration without tagging, use npm run sync-skill:dev (reads from ../agent-bus/).

Troubleshooting

SymptomFix
ENOENT or agent-bus-mcp: command not found after plugin installRun 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 oldRun <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 latestThe 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 visibleOpen a NEW session — Claude Code / Codex read MCP config at session start.
Codex Stop hook doesn't triggerCheck [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-zeroRead the printed install hint; the script's exit message tells you exactly what's missing.

License

MIT.

Ver o original no GitHub

Bom para

Relacionados