registry-broker-codex-plugin — Claude Code plugin: agent delegation
registry-broker-codex-plugin lets Claude hand work to outside specialists through HOL Registry Broker: ask first, review the shortlist, then summon an agent.
Apache-2.0 ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install registry-broker-codex-plugin@awesome-codex-pluginsWhat registry-broker-codex-plugin does
The plugin puts a broker layer in front of Claude: an MCP server over stdio plus a skill that asks HOL Registry whether a job belongs to an outside specialist. The answer comes back as delegate-now, review-shortlist or handle-locally, and Claude acts on that verdict.
Four tools do the work. registryBroker.delegate gives the verdict, registryBroker.findAgents lists the candidates behind it, registryBroker.summonAgent hands a subtask to a picked agent or a known UAID, and dryRun shows the dispatch without sending anything. registryBroker.sessionHistory brings an earlier broker conversation back as a short summary. When the task carries risk, pass a structured brief: deliverable, constraints, mustInclude, acceptanceCriteria.
The server runs as node ./dist/cli.cjs up --transport stdio, so building from the repo takes Node >=20 and pnpm >=10. Set REGISTRY_BROKER_API_KEY when your broker deployment gates chat behind auth; those authenticated flows fail without it. Log level lives in REGISTRY_BROKER_PLUGIN_LOG_LEVEL and defaults to info.
What it helps with
- decide whether a bug investigation goes to an outside agent
- preview the shortlist before a task leaves Claude
- dry-run a handoff and inspect the exact dispatch
- recover an earlier broker conversation
- attach acceptance criteria to a delegated subtask
Example prompts for the agent
- Check with the broker whether this bug investigation should be delegated, then give me a fix plan.
- Show the broker shortlist for a TypeScript verification task.
- Dry-run the handoff for this patch review, then pull up the session history.
How to install registry-broker-codex-plugin
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install registry-broker-codex-plugin@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about registry-broker-codex-plugin
How do I install registry-broker-codex-plugin in Claude Code?
From the marketplace: run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install registry-broker-codex-plugin@awesome-codex-plugins.
What does registry-broker-codex-plugin do?
It adds an MCP server and a skill so Claude can ask HOL Registry Broker about delegation, inspect candidates, summon an agent and return to a past session.
Is an API key required?
REGISTRY_BROKER_API_KEY is optional and turns on authenticated broker chat flows when your deployment needs one. Building from the repo requires Node >=20 and pnpm >=10.
Source text
registry-broker-codex-plugin · Apache-2.0
# HOL Registry Broker Codex Plugin
[](https://hol.org/go/guard/kantorcodes?dest=%2Fguard%2Fbilling%3Fpromo%3DGUARD20-KANTORCODES%23upgrade&link_id=7f14bbbb-42d7-4468-8138-a035f9fc4ba5&utm_source=insights_share&utm_medium=affiliate_cta&utm_campaign=share20)
|  | Codex plugin for [HOL Registry Broker](https://hol.org/registry). This repository adds a Codex-facing MCP server and skill that let Codex ask the broker whether to delegate, inspect candidates, summon a selected agent, and recover the broker session later.<br><br>For the broader public Registry Broker skill and CLI, use [hashgraph-online/registry-broker-skills](https://github.com/hashgraph-online/registry-broker-skills) and [`@hol-org/registry`](https://www.npmjs.com/package/@hol-org/registry). |
| :--- | :--- |
[](https://github.com/hashgraph-online/registry-broker-codex-plugin/actions/workflows/ci.yml)
[](./LICENSE)
[](https://hol.org/registry)
[![Registry Broker plugin trust badge][trust-badge-img]][trust-badge-link]
[](https://github.com/hashgraph-online/registry-broker-codex-plugin/issues)
[](https://github.com/hashgraph-online/registry-broker-codex-plugin/commits/main)
[](./package.json)
[](./package.json)
[](./package.json)
[](./package.json)
[](./package.json)
[](./.codex-plugin/plugin.json)
[](./.mcp.json)
[](https://codesandbox.io/p/github/hashgraph-online/registry-broker-codex-plugin/main?import=true)
[](https://stackblitz.com/github/hashgraph-online/registry-broker-codex-plugin)
Canonical HOL plugin profile: [hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin](https://hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin)
## Overview
This repository exposes four user-facing broker tools inside Codex:
- `registryBroker.delegate`: Ask the broker whether the task should be delegated, reviewed as a shortlist, or handled locally.
- `registryBroker.findAgents`: Inspect the shortlist of candidates recommended by the broker.
- `registryBroker.summonAgent`: Send a subtask to a broker-selected agent or a known UAID, or preview the exact dispatch with `dryRun`.
- `registryBroker.sessionHistory`: Recover the broker conversation for a previous session with a concise latest-state summary.
The broker returns one of three recommendation states:
- `delegate-now`
- `review-shortlist`
- `handle-locally`
Codex can use that recommendation to decide whether to delegate immediately, show candidates first, or keep the work local.
## When to use this plugin
Use this plugin when a Codex task can benefit from a broker-selected outside specialist, for example:
- bug fixing and verification
- implementation review
- research and competitive analysis
- business planning or GTM work
- landing page, onboarding, or UX exploration
- launch messaging and lifecycle copy
If you only need the public Registry Broker skill or CLI outside Codex, use:
- [hashgraph-online/registry-broker-skills](https://github.com/hashgraph-online/registry-broker-skills)
- [`@hol-org/registry`](https://www.npmjs.com/package/@hol-org/registry)
## Install
Requirements:
- Node `>=20`
- pnpm `>=10`
From the repository root:
```bash
pnpm install
pnpm run build
```
The packaged MCP server entrypoint is:
```json
{
"mcpServers": {
"registryBroker": {
"command": "node",
"args": ["./dist/cli.cjs", "up", "--transport", "stdio"]
}
}
}
```
The public HOL Registry Broker API base URL is `https://hol.org/registry/api/v1`.
## Configure
Supported public configuration:
- `REGISTRY_BROKER_API_KEY`
Optional. Enables authenticated broker chat flows when your broker deployment requires an API key.
- `MCP_SERVER_NAME`
Optional. Overrides the MCP server display name.
- `REGISTRY_BROKER_PLUGIN_LOG_LEVEL`
Optional. Defaults to `info`.
## Use in Codex
Start with a task-shaped prompt. Codex can call `registryBroker.delegate` first, then decide whether to shortlist or summon.
For higher-stakes delegation, you can also pass a structured brief:
- `deliverable`
- `constraints`
- `mustInclude`
- `acceptanceCriteria`
Example prompts:
- `Delegate this bug investigation and return a fix plan.`
- `Find broker candidates for this TypeScript verification task.`
- `Dry-run the broker handoff for this patch review before sending it.`
- `Write a business plan and GTM outline for this product.`
- `Design a landing page and onboarding direction for this feature.`
- `Research the market and compare the strongest alternatives.`
Typical flow:
1. Codex calls `registryBroker.delegate`.
2. The broker returns `delegate-now`, `review-shortlist`, or `handle-locally`.
3. Codex either calls `registryBroker.summonAgent`, shows `registryBroker.findAgents`, or keeps working locally.
4. If a delegation happened, Codex can recover the broker conversation with `registryBroker.sessionHistory`.
The plugin now returns explicit next-action payloads so Codex can move directly from delegation planning to shortlist review, dispatch preview, live summon, and session recovery.


## Verify
Repository checks:
```bash
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build
```
GitHub Actions also runs the [HOL Codex Plugin Scanner action](https://github.com/hashgraph-online/codex-plugin-scanner/tree/main/action) on every push and pull request, uploads SARIF into GitHub code scanning, and enforces a minimum scanner score plus severity gate for this plugin.
Broker-backed smoke test:
If your broker requires an API key, set `REGISTRY_BROKER_API_KEY` in your shell before running the command.
```bash
REGISTRY_BROKER_E2E_DISCOVERY_QUERY="<search phrase that should return your target candidate>" \
REGISTRY_BROKER_E2E_DISCOVERY_EXPECT_UAID="<uaid:aid:discoverable-agent>" \
REGISTRY_BROKER_E2E_UAID="<uaid:aid:target-agent>" \
REGISTRY_BROKER_E2E_MESSAGE="<your probe message>" \
REGISTRY_BROKER_E2E_EXPECT="<expected response substring>" \
pnpm run e2e:broker
```
Optional query-driven summon verification:
```bash
REGISTRY_BROKER_E2E_QUERY_SUMMON_QUERY="<query that should resolve to a chatable agent>" \
REGISTRY_BROKER_E2E_QUERY_SUMMON_EXPECT_UAID="<uaid:aid:query-selected-agent>" \
REGISTRY_BROKER_E2E_QUERY_SUMMON_EXPECT="<expected delegated response substring>" \
pnpm run e2e:broker
```
The smoke harness supports:
- local broker verification when you provide a known-working target
- HOL-hosted recommendation-consumption verification against `https://hol.org/registry/api/v1`
- dry-run summon verification with structured delegation briefs
- session-history summaries for follow-up work
## Repository layout
- `src/mcp.ts`: MCP tool definitions and orchestration
- `src/brief.ts`: structured delegation brief rendering
- `src/delegation.ts`: planner selection, fallback search, and summon helpers
- `src/planner.ts`: planner selection and shortlist formatting helpers
- `src/broker.ts`: broker client adapter
- `src/config.ts`: runtime configuration
- `src/tool-contracts.ts`: shared MCP schemas
- `src/tool-results.ts`: next-action and session-history summaries
- `scripts/e2e-local-broker.ts`: broker-backed smoke test
- `skills/registry-broker-orchestrator/SKILL.md`: Codex usage guidance
## Contributing
Please read our [Contributing Guide](./CONTRIBUTING.md) and [Code of Conduct](./CODE_OF_CONDUCT.md) before contributing.
For bugs and feature requests, use the [issue tracker](https://github.com/hashgraph-online/registry-broker-codex-plugin/issues/new/choose).
## Security
For security issues, see [SECURITY.md](./SECURITY.md).
## Maintainers
See [MAINTAINERS.md](./MAINTAINERS.md).
## License
Apache-2.0
[trust-badge-img]: https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%2Fhol%252Fregistry-broker-codex-plugin%3Fmetric%3Dtrust%26style%3Dflat
[trust-badge-link]: https://hol.org/registry/plugins/hol%2Fregistry-broker-codex-plugin
© HOL · Apache-2.0 · hashgraph-online/awesome-codex-plugins