SuperBrain: Connecting Agents to an External Brain

When command-line tools such as Claude, Codex, Kimi, and Qoder CN all exist locally at the same time, the core pain point in engineering implementation is no longer "model capability," butHow to build a unified scheduling layer that remains maintainable over the long term: who does the scheduling, how arguments are passed to prompts, and how to tolerate changes in output format.

SuperBrain is positioned asA connection and coordination intermediary layer between the host Agent and external CLIs, aimed at standardizing external CLI integration into configurable, versionable engineering components.

Skill source code address:https://github.com/Niall-Young/SuperBrain

Where it can be installed, who it can call

SuperBrain is an Agent Skill that you need to call explicitly. The host Agent must have at least Skill and sub-agent capabilities; whether it is compatible still needs to be confirmed against the host's actual capabilities. The project documentation uses Claude Code as an example host, and the installation instructions list the skills directories corresponding to hosts such as Cursor, Windsurf, and Codex—note that these are examples and directory descriptions, and compatibility has not been tested one by one. Who it can call: this source package includes four external-brain CLI seats—Claude, Codex, Kimi, and Qoder CN. In one sentence, its value is: it turns “external AI” into something configurable and maintainable, rather than a one-off demo. Below, “where to install it” and “who to call” are explained separately, because they are two different layers.

Two layers of integration: host and external brain

SuperBrain's integration is split into two layers, which is the most easily confused point in this article and the one most worth clarifying first.

The upper layer is the host Agent: it is responsible for hosting the Skill, the explicit invocation flow, and integrating results, and it needs both Skill and sub-agent capabilities. The lower layer is the external-brain CLI: it acts as the seats at the round table, where each seat is an installed command-line tool responsible for answering independently. The two layers have completely different integration and verification methods—the host is judged by capabilities, while the external brain is judged by whether the tool is installed, whether it can be found, and whether its output can be parsed.

The reason it is easy to confuse is that names cross layers: the project documentation uses Claude Code as the host example, while also listing Codex as both one of the hosts and a default external-brain seat. The same name appearing in two layers does not mean “this host is bound to this external brain.” Before judging, first figure out which layer the statement refers to.

Integration matrix

Putting the two layers into one table, you can screenshot it directly to take away. In the table, “default or example” distinguishes the factory list from illustrative examples; “verification method” tells you what to rely on to confirm availability; “scope of statement” is the qualification to remember together.

A few key points: Claude and Qoder CN both use the claude-json parsing format, while Codex and Kimi each differ—this asymmetry comes from the project's built-in configuration, not a formatting error. In particular, remember this: the executables, transport methods, and parsing formats of the four built-in seats are the default adaptation mappings bundled in this source package; they are not permanent interface commitments for these CLIs. Whether they remain compatible after upgrades must be rechecked using the criteria below.

Default four seats

The four built-in seats are the "factory list," not the current state of your machine. "Supported" does not mean installed, logged in, or having quota.

[Feishu content not yet supported: document widgets]

The configuration allows 2 to 4 unique seats; the workflow has another threshold—if only one seat succeeds in the first round, it cannot proceed to the second round; at least two first-round seats must succeed to meet the threshold. Before your first run, use the project's built-in local self-check to confirm which external-brain CLIs can be found. It only checks whether the executables exist and whether they can return a version number—even if the self-check finds two executables, that does not mean real calls will necessarily succeed, because login status, quota, and real calls are outside its scope; be sure to remember this. To get it running, at least three prerequisites must also be met: Python 3.9 or above; the host's Skill and sub-agent capabilities; and at least two installed and logged-in external-brain CLIs.

Here is a real snapshot: on August 27, 2026, this machine passed 9 unit tests, and the self-check identified all four default seats as available, with versions Claude Code 2.1.78, Codex CLI 0.150.0, Kimi 0.38.0, and Qoder CN 1.1.31. This is only a record from one machine on one day; another machine may not be the same.

Negotiation mechanism and security boundaries

If you are not satisfied with the default list, you can change it. External seats are overridden wholesale via a JSON configuration—note that this is a wholesale override, not incrementally adding one seat; whichever seats are declared in the configuration are the ones used, and undeclared ones are not retained. Configuration reading has a priority order—command-line argument --config, environment variable SUPERBRAIN_CONFIG, built-in default, taking effect in that order.

[任务下发]
   │
   ├─► 主脑冻结基线（显式阻断：外脑全程不可见主脑观点，削弱先入为主偏差）
   │
   ├─► Round 1: 独立并发作答（隔离工作目录，防相互污染）
   │      │
   │      ├─► [成功节点 < 2] ──► 触发熔断中断 (failed)
   │      │
   │      └─► [成功节点 ≥ 2] ──► 进入 Round 2
   │                                │
   │                                ├─► 数据脱敏同侪复审 (Peer A / Peer B 文本替换)
   │                                └─► 席位二次修订
   │
   └─► 主脑整合输出最终裁决 (生成审计日志: complete / partial / failed)

Each seat must declare six fields: id, label, executable, args, prompt_transport, and output_format, corresponding respectively to the seat identifier, name, executable file, arguments, prompt transport method, and output parsing format. The only optional transport methods are stdin and argv; the only optional output parsing formats are text, claude-json, codex-jsonl, and kimi-jsonl. These are a closed set of options and will not auto-negotiate.

Let's make the boundary clear as well: only a CLI that conforms to these two transports and four parsing contracts can be integrated via a single JSON. This is not "any CLI works plug-and-play with zero code"—the parts beyond the contracts are exactly what the next chapter covers.

Upgrade Path and Three-Level Maintenance Strategy

Three-Level Handling Path

This is the most valuable section of the whole article to take away. The only basis for deciding whether a change calls for a config change or a code change is: can the existing parsing logic still consume this output—not whether the format name in the config has changed. Handling is split into three levels:

Level one, changing the config is enough. The change can still be expressed by the executable, arguments, transport, or an existing output format—switching slots, changing paths, changing arguments, toggling between stdin and argv, switching to an already-supported output format—just modify the JSON config and apply it via --config or SUPERBRAIN_CONFIG.

Level two, after changing the config you must add verification. After any config or environment change: first run the local self-check, then run the unit tests, and finally do a low-risk real consultation. The order can be flexible, but the boundaries must be clear—the self-check only confirms the executable and version; running it alone cannot prove that the login state, real calls, and output parsing are still compatible; the low-risk real consultation is a maintenance recommendation that can fill in the login, real-call, and parsing verification the self-check cannot cover, but it only shows that this one run of the chain succeeded—it is not the only means of verification, nor does it constitute a compatibility guarantee.

Level three: insufficient configuration, requiring code changes and added tests. Both cases count as this level: first, the output structure has changed but the format name has not—the actual output can no longer be consumed by the existing parsing logic, even if the slot still bears an old name like claude-json; second, a completely new output format outside the four is needed—besides changing the parsing logic, you must also extend the supported format set and add protocol documentation and tests.

One sentence to remember the boundary: reusing an old value for the format name does not mean compatibility; and a changed name does not necessarily mean code changes are needed—as long as the shape of the actual output still falls within what some parser can handle, the configuration layer can solve it.

No automatic upgrader

This source package provides no automatic update or automatic migration command—after upgrading the CLI or host, you must synchronize it yourself.

It is recommended to proceed in this order (this is maintenance advice, not a built-in feature): first synchronize the new version of the SuperBrain directory, then retain and re-point your custom slot configuration, then run unit tests and a local self-check, and finally pick one low-risk real issue and consult once.The first two steps address "the code has been replaced with the new version"; the latter two help determine "whether the new environment is still usable"—the self-check only verifies the executable files and versions; a low-risk real consultation can supplement the real invocation and parsing verification that it does not cover, but it only shows that this one link in the chain works.

Treat this sequence as a habit, and SuperBrain turns from a "one-off demo" into an "access layer that can be maintained over the long term".

How it works and why it is trustworthy

Compress the mechanism into one section and explain it clearly. SuperBrain requires an explicit call and by default will not secretly take over tasks. It organizes two rounds of consultation:

The primary brain first freezes its own baseline—forming a judgment before reading any external answer; the request schema explicitly refuses to accept the "primary baseline" field, so the external brains never see it at any point. This is to reduce anchoring: having your own answer first and then listening to others is process-level isolation, which does not equal mathematically eliminating all bias. In the first round, all available seats answer concurrently in their respective independent working directories, unable to see each other; the purpose is to reduce mutual influence and preserve independent perspectives. Only if at least two seats succeed in the first round does it proceed to the second round—each successful seat reads a redacted peer review: known seat names are replaced with labels like Peer A and Peer B; this is a review after identity-string redaction, not strong anonymity, and it is not guaranteed that content style cannot be fully matched to identities. After reading, each revises its own proposal, and finally your primary agent integrates the judgments.

The results are written into an audit record containing the status, time, question, threshold, and each seat's results from both rounds. The status has three states: complete means all configured seats succeeded in the second round, partial means the minimum completion count was reached, and failed means the threshold was not met. Note: complete only means the process was complete, not that the answer is correct—the final judgment is always the responsibility of the primary agent.

Runtime also has limits: seats run in isolated temporary directories, the default Codex seat is a read-only sandbox, and tools are disabled for Claude and Qoder CN; but explicit calls still send the redacted task package to the configured external CLI, so do not put sensitive material into requests. A single call has a default timeout of 180 seconds and an overall timeout of 480 seconds, with no automatic retries; a single seat's output capture limit is 2000000 bytes and the total character limit for request material is 40000, with anything exceeding that being truncated or handled as an error for that seat.