AIWorkHub MCP server
Commit Nov 16, 2026An open-source control plane that manages multi-model AI coding agents using task DAGs, source intelligence, and evidence-based review loops.
Also known as shrec/AIWorkHub
- Stars
- 12
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 16, 2026
- License
- MIT
What is AIWorkHub MCP?
AIWorkHub is an open-source control plane that manages multi-model AI coding agents using task DAGs, source intelligence, and evidence-based review loops.
Summary generated from the project's README
About AIWorkHub MCP server
AIWorkHub acts as an open-source control plane designed to manage a workforce of AI coding agents. It coordinates various models like Claude Code, Codex, and Copilot by treating them as execution routes rather than standalone products. The system splits large projects into specific work cards and distributes them across a portfolio of models, routing simpler tasks to cheaper options to optimize costs.
Users can deploy this server via VS Code extensions or as an MCP server using uvx or Docker. It requires a repository root path to function and manages all state, including indexes and memories, within a local .aiworkhub directory. The platform distinguishes itself through a rigorous review loop where workers submit diffs, tests, and tool receipts for an independent manager to verify before any changes are accepted into the codebase. This ensures that every modification is backed by structural evidence rather than just model claims.
What you can do with it
- 1Dependency-aware project planningThe control plane organizes work into a task DAG to ensure that overlapping or dependent tasks are handled in the correct sequence.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
AIWORKHUB_REPO_ROOT
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableshrec/aiworkhub is public and reachablegithub.com/shrec/aiworkhub ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/shrec/aiworkhub ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAIWorkHub
Proof, from this repository's own history:
- 1,984 commits since 2026-07-20, written through its own task loop
- 347 work cards accepted into its own tree
- 651 times a worker's change was sent back with code-level findings
- 621 independent reviewer passes
- 620 test files, about 262k lines of Python
What makes it different:
- Semantic edit: workers change hash-verified line ranges, never rewrite whole files.
- Review loop: mechanical gates and tests run first, then an independent reviewer reads the code; the manager accepts, returns with findings, or blocks — the same turn.

Quick start: VS Code
- Install from the
VS Code Marketplace
or download the VSIX from the latest
GitHub release and run
code --install-extension ./aiworkhub-<version>.vsix. - Open a Git repository and run AIWorkHub: Open Dashboard.
- Choose Initialize AIWorkHub once. Initialization is explicit and
idempotent: it creates
.aiworkhub/, starts the first Source Graph index and keeps it fresh. The extension runs on Linux, macOS, native Windows, WSL and the Remote-SSH workspace host. - Open a new Codex, Claude or other MCP-capable chat after initializing
(or upgrading) AIWorkHub. The new chat performs tool discovery, finds the
repository MCP tools and receives the MCP Manager Contract banner. Claude
Code also reads the repository-local
.mcp.jsonregistration and AIWorkHub-managedCLAUDE.mdblock: direct Claude chats must bootstrap as managers and use Source Graph before broad built-in file discovery. They are not worker sessions. - Choose the chat that receives callbacks. The built-in Manager (dashboard Manager chat, any backend including Codex models) and Claude Code are woken automatically when a worker finishes. A Codex VS Code sidebar chat is inbox-only and polls the review queue itself; see Callback delivery.
The prompt below is a portable first-run diagnostic for clients that do not automatically honor repository instructions; it is not required in a correctly initialized new Claude Code chat:
Use AIWorkHub as the manager for the currently bound repository.
First call aiworkhub_manager_bootstrap, then verify repository identity,
manager route, callback health, Source Graph readiness and model preflight.
Recover relevant Session Manager state and make one bounded AI Memory query.
Do not edit files, create tasks or launch workers yet. Report what is ready,
what is degraded, and which repository you are authorized to manage.
The response should identify the same repository shown in the dashboard and
report role=manager with a verified route. If it reports an unverified role,
the wrong repository, no tools, or a stale runtime version, stop and use
AIWorkHub: Restart MCP Connection or open a fresh chat. Do not ask the
model to bypass the route or write directly to .aiworkhub databases.
Now describe the outcome in ordinary language. A useful second prompt is:
Plan this outcome with AIWorkHub: <describe the change and constraints>.
Inspect the repository with Source Graph, create bounded dependency-aware
task cards with exact acceptance criteria, allowed writes and validation,
then launch every independent non-colliding ready task in parallel on the
best available models. Keep dependent or overlapping work pending. When a
callback arrives, independently review evidence and accept or reject it.
Give me a short progress report after each accepted wave.
You do not need to name a model. Preflight and Workforce expose the models already authorized in the editor, and the manager chooses a route from live readiness and observed outcomes. Name a model only when you intentionally want to override automatic routing.
Understand the task lifecycle
| State/action | Meaning | Owner |
|---|---|---|
task_create → pending |
A durable card exists; no model is running yet | Manager |
claim + launch → processing |
The exact dependency-ready card was claimed and its worker process started | AIWorkHub runtime |
review_ready |
Worker stopped and submitted diff/tests/logs/artifacts/tool receipts | Worker |
| callback | Wakes the repository's current verified manager; it is not approval | AIWorkHub callback bridge |
| accept or reject | Promote verified work, or preserve evidence and issue exact residual work | Manager |
Never move a card to processing merely because it is pending, and never
infer completion from chat prose. The canonical task receipt is state truth.
All review and terminal categories are callback-eligible. If a connection
drops after a write, reconcile the same task ID; identical retries are
idempotent, while inventing a replacement ID creates duplicate work.
First task workflow
- Confirm Preflight is ready and lists at least one editor model or authenticated CLI route. Optional/redundant unavailable routes do not block the repository.
- Ask the manager chat for a bounded task. The canonical card records the objective, acceptance criteria, dependencies, write scope and validation.
- Launch the exact card. The worker uses repository-local Source Graph and durable context inside an isolated task workspace.
- Follow Live Output or wait for the durable terminal callback.
- In Review, inspect the diff, tests, logs, artifacts and tool receipts. Accept to promote the verified change, or reject with exact residual work.
For ongoing work, ask the manager: Inspect the completion inbox, finalize all review-ready tasks from verified evidence, rebase the task DAG, and launch the next dependency-safe parallel wave. Workers never finalize their own work.
The dashboard's Operations dialog explains real tool use, Source Graph modes, model outcomes, latency, token/cost evidence, callback delivery and storage retention. See the complete user guide for multi-repository, Remote-SSH and troubleshooting flows.
Current public channels: VS Code Marketplace and signed-by-checksum GitHub
Release artifacts (VSIX, wheel and source distribution). Marketplace review
can briefly lag a new GitHub tag; the release page and attached SHA256SUMS
remain the exact artifact authority. Open VSX and PyPI jobs remain opt-in; see
Publishing for owner setup.
Quick start: any MCP client
AIWorkHub speaks MCP over stdio, so any MCP client can run it against a repository.
Option A: uvx. Add the server to your client's MCP configuration (until the PyPI package is published, use the release wheel: "args": ["--from", "/path/to/aiworkhub-<version>-py3-none-any.whl", "aiworkhub"]):
{
"mcpServers": {
"aiworkhub": {
"command": "uvx",
"args": ["aiworkhub"],
"env": {
"AIWORKHUB_REPO_ROOT": "/path/to/your/repo"
}
}
}
}
Option B: Docker. Build the image from an AIWorkHub checkout, then run it from the repository you want managed:
docker build -t aiworkhub-mcp .
docker run -i --rm -v "$PWD:/workspace/repo" aiworkhub-mcp
The image defaults to AIWORKHUB_REPO_ROOT=/workspace/repo with writes and
launches off. See Configuration to change either.
Features
- Use models as a portfolio. Keep frontier models for difficult judgment, route bounded throughput to lower-cost capable models, and use deterministic tools where no model is needed.
- Delegate safely. Dependency-aware tasks run in bounded workspaces with explicit write scopes, timeouts and cancellation.
- Review evidence, not claims. Diffs, tests, tool-use receipts, artifacts and approval history travel with every task.
- Keep repositories isolated. Every repository owns its
.aiworkhub/state, callbacks, indexes, memories and audit trail.
AIWorkHub is an open-source control plane for multi-model AI coding agents. Codex, Claude, Copilot, DeepSeek and GLM are not products it tries to replace; they are execution routes in its workforce. It supplies the repository-scoped planning, context, isolation, evidence, review and economics layer that lets expensive and economical models work together as one system.
| Area | Current capability |
|---|---|
| Tasks | Dependency DAG, collision checks, isolated workers, truthful terminal states and manager review |
| Context | Repository-scoped Session Manager, AI Memory and KB read/write MCP tools |
| Quality | Deterministic verification, combined-tree validation, diff-scoped multi-language Known Bug Scanner, truth-preserving SARIF 2.1.0 export and configurable evidence gates |
| Operations | KPI charts, Review Inbox, callbacks, live output, authenticated all-tool telemetry, bounded logs, reversible task/archive retention and workforce scoring |
| Platforms | Linux, Windows, macOS and Remote-SSH release qualification |
The KPI view separates explicit manager decisions from worker terminal outcomes and plots only bounded repository evidence. Its larger aggregate-only history shows Source Graph modes, workflow stages, latency, inter-call gaps, returned structural evidence, index generations, tool-use cohorts, deterministic raw-path-versus-delivered-bundle byte economics, authenticated receipt conformance, repeated-query discipline, compact-replay bytes and imported runtime coverage. The repository also ships registry-driven retrieval precision, eval-artifact truth, per-test suite profiling, risk precision, no-net-growth and matched A/B instruments. This is structural evidence, not a token multiplier. Every rate carries its sample window or denominator; token savings and causal quality gains are deliberately not inferred. Inter-call gaps at or above the bounded 15-minute informational threshold are surfaced, but never mislabeled as proof that a model was inactive.
The canonical combined review surface is aiworkhub_completion_inbox. Tool
availability and write authority are reported by the live MCP runtime; clients
should discover the schema rather than copy a frozen tool list from docs.
Archive and storage lifecycle
AIWorkHub does not require repositories to keep task history forever. The Storage view can preview archived tasks older than 30, 90, 180 or 365 days, move an exact digest-bound batch into repository-local quarantine, restore it during a seven-day undo window, and separately purge expired quarantine payloads. Tasks with undelivered callbacks are protected, active/review tasks cannot enter this cleanup path, and a compact audit record survives payload purge. Individual completed tasks can also be archived or restored from the task detail view.
Retention defaults are repository-local and configurable in Settings. Preview never mutates data; quarantine and permanent purge require separate explicit confirmation.
Three layers of model economics
| Lever | What AIWorkHub changes | User benefit | Current evidence boundary |
|---|---|---|---|
| Token efficiency | Source Graph discovery, bounded reads, focused context and replacement-only semantic edits | Less avoidable input and code-generation output on eligible work | 31,998 file bytes versus 531 replacement bytes is a verified 60.26× code-output shape ratio; total provider-token multiplier remains unmeasured |
| Model-mix efficiency | Routes bounded throughput to lower-cost capable models and reserves premium models for hard judgment or review | The same useful workload can consume fewer expensive-model tokens even when total tokens are unchanged | In one 36-run Claude cohort, Opus was 19% of tokens but 42.9% of known cost; quality-adjusted cross-model savings are the next required measurement |
| Attempt efficiency | Separates launch, validation, timeout and review failures so residual work can be repaired instead of blindly repeated | Fewer expensive retries and clearer reasons for rework | 47 of 114 historical attempts were retries and used 88.31M tokens; this locates the opportunity but does not claim every retry was avoidable |
These levers compound: reducing a task's unnecessary tokens and then running the remaining bounded work on a cheaper capable model can lower cost more than either optimization alone. Every saving still has to preserve validation and manager-accepted quality; a cheap failed run is not an economic success.
Where AIWorkHub sits
| Layer | Examples | Relationship to AIWorkHub |
|---|---|---|
| Repository control plane | AIWorkHub | Owns task truth, dependencies, routing, context authorities, isolation, evidence, callbacks, review and economics telemetry |
| Supported execution workforce | Codex, Claude, Copilot-hosted models, DeepSeek, GLM | Models and agent runtimes AIWorkHub coordinates; they are not competitors |
| Adjacent context/edit tooling | Graphify, Serena and similar graph or semantic toolkits | Complementary ideas/capabilities; they do not provide the same complete repository control loop |
| Standalone coding-agent products | Aider, Cline and similar clients | Alternative execution experiences, not the same product layer |
| Actual alternative today | Manual multi-chat coordination or custom in-house glue | The workflow AIWorkHub replaces: copy/paste context, hand-managed worktrees, retries and review state |
Source intelligence and durable context
AIWorkHub has two graphs with different authority. They are complementary, not alternate names for the same feature.
| Surface | What it represents | Who uses it |
|---|---|---|
| Source Graph | An automatically refreshed structural index with 34 configurable code/data/documentation families and exactly 38 bounded query modes, including exact-target file, function, class, body, bodygrep and deps modes, used to return repository context instead of repeatedly scanning the tree |
Managers and workers |
| Manager Context Graph | An opt-in, append-only ledger and deterministic graph of manager conversation evidence across repository, thread, session and task identities | Verified managers only |
The Manager Context Graph can search an earlier decision, recover the exact bounded transcript range around it and follow deterministic relations to its thread, session or task. It does not replace Session Manager (current state and handoffs), AI Memory (durable lessons), KB (curated project knowledge), or the Source Graph (code intelligence). Current passive capture supports completed Codex user/assistant messages; reasoning, streaming deltas, tool output, commands and approvals are excluded. Claude and Copilot capture adapters are not yet claimed as shipped.
For existing-file changes, the worker can stay on a focused path end to end.
Source Graph body returns one bounded symbol with exact line evidence; the
model emits only replacement code; AIWorkHub's local Python applier verifies the
complete-file preimage, the prepared fragment, write scope and range before
changing the isolated worktree. Full-file output remains available only as a
legacy fallback or for genuinely new files. Receipts report file, fragment and
replacement bytes, but do not turn those byte counts into an invented token
savings multiplier. Text-only and native VS Code LM providers can submit these
fragments one at a time; the local bridge validates hashes and overlaps, retains
no workspace mutation during staging and assembles the final response offline.
AIWorkHub reports context evidence rather than making an unverifiable savings claim: requested/delivered bytes, acknowledged tool receipts, truncation and degraded reasons remain distinguishable. See the Source Graph guide, Manager Context Graph and Source Graph economics for the contract.
Measured benefits and limits
The checked-in benchmark ledgers are recomputed in CI and include favorable,
negative and still-unmeasured results. Missing populations are shown as
not_configured, inconclusive or unknown; they never become zero or a
synthetic savings multiplier.
| Evidence | Current observation | Status |
|---|---|---|
| Focused-edit paired pilot | Historical capped A/B observation: 27.5% fewer total tokens, 24.9% fewer output tokens and 21.5% less elapsed time across two pairs, but pair 1 used mismatched 20k/200k token ceilings |
Not eligible for a causal or product-savings claim; uncapped matched rerun required |
| Authenticated edit shape | 531 replacement bytes for 31,998 existing-file bytes (1.66%; 60.26× structural ratio), with zero old bytes re-emitted | Verified reduction in emitted code payload when a full-file baseline applies; not a 60.26× claim for the complete provider bill |
| Current Source Graph gate | 7/7 gated tasks used live graph evidence; 13 calls, 0 failures; p50 15.024 ms | Verified runtime snapshot |
| Callback durability | 271 events, zero dead letters and zero backlog | Verified runtime snapshot |
| Context Bundle v2 encoding | One same-evidence representative fixture shrank from 849 to 600 bytes (29.329%) | Verified structural fix; live fleet remeasurement pending |
See Benchmarks for the full evidence matrix, denominators, adjacent-tool capability boundaries, raw ledgers and the promotion gate required before publishing any universal savings claim.
Supported models
AIWorkHub routes by runner family and adapter. Editor routes use models already visible in VS Code; CLI routes reuse that CLI's own authenticated session. AIWorkHub does not copy editor or CLI credentials.
| Runner family | Supported route | Install requirement | Credential |
|---|---|---|---|
codex_* |
codex_cli or VS Code LM |
Codex CLI/extension, or a VS Code LM provider | Existing Codex login, or one-time VS Code model consent |
claude_* |
claude_cli or VS Code LM |
Claude Code CLI/extension, or a VS Code LM provider | Existing Claude subscription login, or one-time VS Code model consent |
deepseek_* |
DeepSeek V4 Pro/Flash through VS Code LM; Copilot CLI BYOK fallback | DeepSeek-capable VS Code provider; fallback requires GitHub Copilot CLI | VS Code model consent; fallback uses aiworkhub-deepseek-credential set |
glm_* |
GLM 5.3 through VS Code LM; Copilot CLI BYOK fallback | GLM 5.3 visible in VS Code; fallback requires GitHub Copilot CLI | VS Code model consent; fallback uses python -m aiworkhub.glm_credentials setup |
copilot_* |
Public VS Code Language Model API | GitHub Copilot extension | GitHub sign-in and one-time model consent |
Exact model availability is discovered at runtime because subscriptions and editor model catalogs differ. The editor broker starts automatically, performs credential-free discovery and asks for consent only when an exact queued task first invokes that model. In Remote-SSH, the workspace extension uses VS Code's Language Model API to consume the model catalog exposed by the client window; it does not look for a second provider credential on the SSH host. The dashboard keeps models visible in the editor separate from execution routes.
Configuration
The MCP server reads these environment variables. Writes and launches are off unless you turn them on.
| Variable | Default | Purpose |
|---|---|---|
AIWORKHUB_REPO_ROOT |
Unset: the nearest .aiworkhub/project.json above the working directory within its Git repository, else that Git root |
Repository the server binds to; when set it takes precedence over the working directory |
AIWORKHUB_ALLOW_WRITES |
0 |
Only the exact value 1 enables write tools |
AIWORKHUB_ALLOW_LAUNCH |
0 |
Only the exact value 1 enables worker launches, and launches also need AIWORKHUB_ALLOW_WRITES=1 |
AIWORKHUB_MAX_PROCESSES |
4 |
Cap on workers running at once; values below 1 become 1 and values above 32 become 32 |
AIWORKHUB_PROVIDER_LAUNCH_LIMITS |
opencode-go=1 |
Per-provider launch limits as provider=limit pairs, for example opencode-go=1,xai=2; listed providers override the default entry by entry |
Enable writes and launches only in a trusted manager process. Launched workers never inherit the manager launch capability.
How it works
flowchart LR
A[VS Code and MCP clients] --> B[Repository-bound AIWorkHub runtime]
B --> C[Plan DAG and task queue]
B --> D[Source Graph]
B --> E[Session, Memory and KB]
C --> F[Isolated model workers]
F --> G[Evidence bundle]
G --> H[Manager review]
H -->|accept or rework| C
The MCP server uses stdio only. Writes and process launches are independently disabled by default. Credentials stay outside the repository, callback events are durable and repository state remains local.
The full block diagram and the Observe → Decide → Delegate → Verify → Promote → Learn loop: The whole system.
AIWorkHub MCP questions
What models can AIWorkHub use?
It can use various models including Claude Code, Codex, Copilot, DeepSeek, and GLM as execution routes in its workforce.
How does AIWorkHub ensure code quality?
It uses a review loop with mechanical gates, tests, and an independent reviewer that checks diffs, logs, and artifacts before accepting changes.
Can I run AIWorkHub with any MCP client?
Yes, it speaks MCP over stdio, allowing it to run against a repository using any MCP client via uvx or Docker.
Does it support different operating systems?
Yes, the extension is qualified for Linux, Windows, macOS, and Remote-SSH.