Universal Brute Workpack

npm version npm downloads license: BUSL-1.1 node >=20

可以把它理解成“Codex 和任意 MCP Agent 都能用的通用版 OpenClaw SC”：默认百路、可配置100+ Agent 流水线 + 跟随全部可用 CPU 并行度的本地 Worker。

Universal Brute Workpack（UBW）把一个普通 Agent 客户端升级成本地满配工作台。Codex、OpenClaw、Claude Desktop、Cursor、Cline、Continue 或其他 MCP 客户端，都可以通过一个服务获得并行 Agent、本地多核 Worker 和完整工具链。

它最强的地方

1. 100+ Agent 流水线

默认支持最多100个流水线任务，任务上限和并发数都可以配置提高。适合大面积全网调研、代码审计、日志扫描和多方案探索。

2. 真正使用本机全部可用 CPU 并行度

本地 fs.grep、文件分析、切片、diff 和批处理通过 Worker Threads（工作线程）运行。默认 Worker 池自动跟随机器可用 CPU 并行度，多核机器不再闲着。

3. 本地 Worker 不花模型 Token

能用 CPU 完成的搜索、哈希、统计和差异分析，不需要让昂贵模型逐个处理，速度更快，成本接近零。

4. 便宜模型跑广度，强 Agent 做判断

大批量探索可以交给便宜 API 模型；Codex Pro 或其他强 Agent 保留给规划、复审、合并和最终裁决。

5. 一个 MCP 补齐整套本地能力

文件读写、并行 grep、命令执行、网页搜索兜底、记忆召回兜底、代码补丁、验证、Agent 派生和流水线都在一个 Workpack 里。

6. 代码补丁失败可以自动回撤

code.patch 使用精确替换；JS 类文件修改后自动运行 node --check，语法失败就恢复原文件。

7. 服务缺一块，其他能力仍能继续工作

没有配置 LLM 时，本地文件和 Worker 工具仍然可用；外部搜索、记忆或 Agent 服务可以按配置逐级启用，不需要整套系统一起停摆。

8. 不绑定某一个 Agent 框架

它通过 MCP 的 stdio、Streamable HTTP 或 legacy SSE 提供能力，可以作为多个 Agent 客户端共用的本地执行层。

最简单的用法

安装后可以直接让 Agent：

用 UBW 把这个仓库切片并行搜索
用本地多核 Worker 扫描所有文件
把这个问题拆成100路 Agent 调研
用便宜模型跑批量候选，最后由主 Agent 复核
修改这段代码，验证失败自动回撤

默认 Agent 流水线最多100个任务、默认20并发；可以通过 UBW_AGENT_MAX_PIPELINE_TASKS 和 UBW_AGENT_CONCURRENCY 调整。大规模 API Agent 任务会真实产生模型费用，本地 Worker 任务不消耗模型 Token。

English quick overview

Universal Brute Workpack is a portable, MCP-native edition of the OpenClaw sc idea:

• 100 pipeline tasks by default, configurable beyond 100;
• local worker pools that follow available CPU parallelism;
• zero-token local grep, slicing, hashing, analysis, and diff;
• API-backed Agent pipelines for wide research and audits;
• rollback-aware code patching;
• files, commands, search, memory fallback, validation, and evidence collection behind one MCP server;
• support for Codex, OpenClaw, Claude Desktop, Cursor, Cline, Continue, and other MCP clients.

Capability Model

Available now:

• Full-capability MCP tool bundle with stdio, Streamable HTTP, and legacy SSE transports.
• 26 neutral tools for search, fetch, file operations, code patching/review, commands, validation, memory search/recall, worker analyze/diff, audit chain, status, and Agent spawn/pipeline.
• Codex installer defaults to codex_daily, exposing 12 low-noise tools for web search, bulk file discovery, CPU-parallel grep, read-only review, and validation. Full capability remains available through explicit profiles.
• CPU-parallel fs.grep through a local worker pool. By default it uses available machine parallelism; set UBW_WORKER_POOL_SIZE only when you want to limit it.
• code.patch uses exact replacements and rolls back JS-like files when node --check fails.
• Managed sidecar mode for agent.spawn and agent.pipeline; users do not need to start a second terminal for the sidecar.
• Concurrent API-backed agent.pipeline with configurable task cap, concurrency, stagger timing, and timeout.
• TaskCard/runDir/collector/EvidenceBundle audit chain through audit.prepare, audit.ingest_report, audit.run, and audit.collect.
• Zero-key first run: DuckDuckGo/direct HTTP fallback for web search and local text/JSON/Markdown/log fallback for memory search.
• Configurable profiles, deny lists, filesystem roots, provider keys, memory backends, LLM endpoints, pipeline task limits, and stagger timing.
• OpenAI-compatible API mode for agent.spawn and agent.pipeline; if no model backend is configured, Agent tools return not_configured instead of killing the MCP process.
• Optional Codex companion skills under integrations/codex-skills/: a general ubw boundary guide plus the advanced ubw-audit entry.
• Optional Codex plugin wrapper under plugins/universal-brute-workpack/ plus .agents/plugins/marketplace.json for users who want UBW to appear in the Codex plugin UI.

Proven pattern / current portable base:

• OpenClaw has already demonstrated 100-way prompt-contained pre-audit as an external orchestration pattern.
• Universal Brute Workpack now ships the portable base for that pattern: local worker pool, managed sidecar, concurrent pipeline controls, TaskCards, run directories, collector contracts, EvidenceBundles, failure thresholds, and main-Agent review gates.
• Host-mediated mode lets Codex/Cursor/Cline/other Agent hosts create native subagents while UBW owns prompts, report ingestion, collection, and gate artifacts.
• The high-value path is a two-layer audit loop: broad low-cost candidate discovery, then focused high-quality review by a smaller number of stronger Agents.

Quick Start

For Codex, run the installer once:

npx -y [email protected] install codex

Then restart Codex. The installer copies UBW into a stable local version path, backs up ~/.codex/config.toml, replaces mcp_servers.ubw, and makes Codex run node .../src/bridge.js directly instead of keeping npx in the daily MCP process tree. Codex installs use --profile codex_daily by default to keep the everyday tools list small.

Verify the local Codex registration with:

npx -y [email protected] doctor --codex --profile codex_daily

Rollback the Codex config backup with:

npx -y [email protected] rollback codex

Other MCP clients can auto-start the workpack with npx:

{
  "mcpServers": {
    "ubw": {
      "command": "npx",
      "args": ["-y", "[email protected]", "serve", "--stdio"]
    }
  }
}

Manual Codex config is still available as an advanced fallback:

[mcp_servers.ubw]
command = "npx"
args = ["-y", "[email protected]", "serve", "--stdio", "--profile", "codex_daily"]

For normal Codex use, prefer --profile codex_daily; use admin only when you intentionally want the full tool surface. The one-command installer is preferred for Codex because it writes a stable local node .../src/bridge.js registration and avoids an extra npx Node process per UBW MCP instance.

The MCP setup gives Codex the tools, but it does not make UBW appear in Codex's plugin browser or @ plugin picker.

If you want the plugin UI experience, install the optional Codex plugin wrapper from this repository's marketplace. This does not require official marketplace curation; a user can add this repository marketplace directly:

codex plugin marketplace add <path-or-repo-root-containing-.agents/plugins/marketplace.json>
codex plugin add universal-brute-workpack@universal-brute-workpack

That wrapper is skills-only; register the MCP server once in top-level Codex config as mcp_servers.ubw. If your Codex build exposes plugin installation through the app UI instead of the CLI, add this repository marketplace there, install the wrapper, then start a new thread before @Universal Brute Workpack is visible.

No API key is required for first run. In codex_daily, search.web, local file discovery, CPU-parallel grep, read-only review, and validation work out of the box. Memory fallback, audit dispatch, raw Agent tools, URL fetch, writes, and command execution are available only when you explicitly choose a profile that exposes them.

If Tavily or Exa is not configured, exhausted, or unavailable, search.web falls back instead of crashing. If no memory/vector service is configured, memory.search falls back to local text search. If no LLM endpoint is configured, agent.spawn and agent.pipeline report not_configured while every local tool continues working.

Optional Codex Plugin Wrapper

There are two Codex integration layers:

Layer	What It Does	Install Path
MCP server	Gives Codex the actual UBW tools through a stable local node .../src/bridge.js command.	Run npx -y [email protected] install codex.
Codex plugin wrapper	Makes UBW show as a Codex plugin and bundles the companion skills. It does not register a second MCP server.	Add this repository marketplace, then install from .agents/plugins/marketplace.json.

The plugin wrapper is manual for now. npm cannot automatically register a Codex plugin in every user's app, and official marketplace curation is not required for self-distribution. The wrapper is included so users can install the companion skills deliberately while keeping the MCP server registered once in top-level config. The install codex command handles the MCP server registration; the plugin wrapper is only for plugin UI and skills.

Registry Metadata

The package includes draft-ready official MCP Registry metadata in server.json and package.json#mcpName. See docs/distribution.md for the registry, aggregator, Smithery, and Codex plugin-wrapper status before publishing a new release.

MCPB Bundle

For the local stdio bundle route, UBW can stage, validate, and pack an MCPB directory:

npm run mcpb:stage
npm run mcpb:validate
npm run mcpb:pack

See docs/mcpb.md. This is separate from Smithery URL publishing, which still requires a public HTTPS Streamable HTTP endpoint.

Optional Codex Skills

Codex users can copy the lightweight companion skills so Codex loads short scenario guides instead of repeatedly reading the full UBW manual:

Copy-Item -Recurse .\integrations\codex-skills\ubw* "$env:USERPROFILE\.codex\skills\"

Included skills: ubw and ubw-audit.

Example Use Cases

After connecting the MCP server, call tools from your Agent client:

search.web
query: "latest MCP client stdio configuration"

fs.grep
root: "."
pattern: "TODO"
maxResults: 50

worker.diff
left: "src"
right: "backup/src"
maxFiles: 10000

code.review
path: "src"
maxFiles: 200
maxFindings: 30

agent.pipeline
tasks:
  - prompt: "Review src/tools/core.js for command execution risks."
  - prompt: "Review src/lib/profiles.js for profile bypass risks."
model: "cheap-review-model"
concurrency: 20
staggerMs: 50

audit.prepare
tasks:
  - title: "Review tool permissions"
    prompt: "Find profile bypasses and report compact JSON findings."
maxFindingsPerTask: 3

If no LLM endpoint is configured, Agent tasks return not_configured instead of crashing. Local tools still work.

Environment Quick Reference

Variable	Default	Purpose
UBW_CONFIG	package example config	Path to a custom main config JSON.
UBW_PROFILES	package example profiles	Path to a custom profile/deny JSON.
UBW_PROFILE	admin	Active profile.
UBW_ROOTS	*	Allowed filesystem roots, separated by ;.
UBW_WORKER_POOL_ENABLED	1	Enable CPU worker pool for local bulk work.
UBW_WORKER_POOL_SIZE	available CPU parallelism	Override worker pool size; empty means auto.
UBW_WORKER_MIN_PARALLEL_FILES	1	Minimum candidate files before parallel grep.
UBW_WORKER_MAX_FILE_BYTES	2000000	Per-file worker scan cap.
TAVILY_API_KEY	empty	Optional Tavily web search key.
EXA_API_KEY	empty	Optional Exa web search key.
UBW_MEMORY_URL	empty	Optional external memory/vector service endpoint.
LLM_BASE_URL	empty	Optional OpenAI-compatible base URL for Agent tasks.
LLM_API_KEY	empty	Optional model API key.
LLM_MODEL	provider default	Optional model name.
UBW_SIDECAR_MODE	managed	managed, inprocess, or external.
UBW_SIDECAR_URL	empty	External sidecar URL when using external mode.
UBW_SIDECAR_PORT	0	Managed sidecar port; 0 means auto-pick.
UBW_AGENT_MAX_PIPELINE_TASKS	100	Pipeline task cap.
UBW_AGENT_CONCURRENCY	20	Concurrent Agent tasks inside pipeline.
UBW_AGENT_STAGGER_MS	0	Delay between pipeline tasks.
UBW_AGENT_TASK_TIMEOUT_MS	300000	Agent task timeout.
UBW_AGENT_TASK_HISTORY_LIMIT	1000	Managed sidecar task record cap.

Defaults

• Tool names are neutral: search.web, file.read, command.exec, agent.spawn, and so on.
• Raw serve default mode is full capability: profile=admin, roots=["*"].
• install codex defaults to profile=codex_daily, which exposes search.web, fs.*, file.read, worker.*, code.review, and validate.* but hides writes, arbitrary commands, URL fetch, memory fallback, audit dispatch, and raw Agent tools.
• Narrow profiles and per-profile deny lists are compatibility and safety knobs for clients that want them.
• Provider keys, memory/vector service URLs, model endpoints, pipeline limits, and stagger timing are configured through config/universal-brute-workpack.example.json, .env, or your MCP client environment.
• memory.search / memory.recall prefer a configured memory service, then fall back to local text/JSON/Markdown/log search instead of failing.
• agent.spawn / agent.pipeline use the managed sidecar by default. Set LLM_BASE_URL, optional LLM_API_KEY, and LLM_MODEL for real model calls.

Start

stdio, for MCP clients:

npx -y [email protected] serve --stdio

Streamable HTTP, for clients or hosted gateways that need a single HTTP MCP endpoint:

npx -y [email protected] serve --transport streamable-http --port 18890 --profile admin

The MCP endpoint is http://127.0.0.1:18890/mcp. A static server card is exposed at http://127.0.0.1:18890/.well-known/mcp/server-card.json.

For a Smithery URL publishing hosting recipe and one-command public endpoint preflight, see docs/smithery-hosting.md.

Legacy SSE, for older clients that prefer a local server:

npx -y [email protected] serve --transport sse --port 18890 --profile admin

Doctor:

npx -y [email protected] doctor

For local development, copy .env.example to .env.

Architecture

Agent Client
  └─ MCP stdio / Streamable HTTP / legacy SSE
      └─ Universal Brute Workpack bridge
          ├─ local tools: fs/search/file/code/command/validate
          ├─ CPU worker pool: parallel grep and local bulk scans
          ├─ fallback tools: DuckDuckGo/direct HTTP, local memory keyword scan
          ├─ managed sidecar: isolated Agent spawn/pipeline process
          └─ audit layer: TaskCards, reports, collector, EvidenceBundles, gate

Tools

See docs/tools.md.

For the host-mediated audit flow, where the host Agent dispatches native workers and UBW owns the runDir, reports, collector, EvidenceBundle, and gate, see docs/host-mediated.md.

Configuration

See docs/configuration.md for provider keys, memory backends, profiles, deny lists, roots, and pipeline limits.

License

Business Source License 1.1. The source is available for personal, research, academic, and small non-commercial use. Enterprise production use, commercial products, SaaS, hosted MCP services, Agent platforms, marketplace redistribution, OEM/white-label use, and commercial derivatives require written authorization from the licensor.

Change License: Apache License v2.0.

Change Date: 2030-06-29.

See LICENSE for the full English and Chinese terms.

FAQ

Do I need an API key?

No for first run. Local tools, DuckDuckGo/direct HTTP fallback, and local memory keyword search work without keys. You only need keys for stronger web providers or model-backed Agent tasks.

Does BUSL restrict personal use?

Personal, academic, research, and small non-commercial use are free under the included license. Enterprise production use, commercial services, SaaS, hosted MCP services, Agent platforms, marketplace redistribution, OEM/white-label use, and commercial derivatives require written authorization before the Change Date.

Is 100-way Agent orchestration already shipped?

The portable base is shipped in v0.1.x: worker pool, managed sidecar, concurrent API pipeline, TaskCards, runDir, report ingestion, collector summary, EvidenceBundle, gate file, optional Codex companion skills, and an optional Codex plugin wrapper. OpenClaw has demonstrated the 100-way pre-audit pattern in a larger system; UBW provides the generic MCP package foundation for that style of workflow. Codex daily installs intentionally keep that surface narrow until a task asks for audit or Agent orchestration.

What happens when keys or quotas are missing?

The workpack degrades instead of dying: Tavily/Exa can fall back to DuckDuckGo/direct HTTP, external memory can fall back to local keyword search, and Agent tools return not_configured without breaking file/search/command tools.

Can this use Codex Pro or another subscription Agent as workers?

Not directly by taking a hidden API key. The host-mediated audit flow lets the host Agent use its own native subagents, threads, or tools while UBW manages task cards, run directories, report ingestion, collector contracts, and evidence bundles.

Contributing

Issues and pull requests are welcome for bug fixes, docs, provider adapters, and safer tool implementations. For development:

npm install
npm run doctor
npm run smoke
npm run smoke:host
npm run smoke:stdio
npm run pack:dry

Verify

node --check .\src\bridge.js
node --check .\src\tools\core.js
node --check .\sidecar\server.js
npm run smoke
npm run smoke:host
npm run smoke:stdio
npm run doctor
npm run pack:dry

Contact

For collaboration, licensing, or partnership inquiries, contact: [email protected]