LightWorker’s MCP server lets you queue, approve, monitor, and control bounded multi-agent Codex/ZCode tasks locally with dependency-aware orchestration and isolated write execution.
Plan and orchestrate dependency-aware task graphs (orchestrate) and delegate explore/review/execute tasks (delegate_task, delegate_batch).
Track task status and trees, wait for terminal/approval states, and read append-only events (get_task, get_task_tree, list_tasks, wait_tasks, get_events).
Inspect cold/warm cache telemetry and target status (get_cache_metrics).
Approve write tasks, cancel queued/active tasks, retry failed read-only tasks on fallback gateways, and escalate read-only retries (approve_task, cancel_task, retry_fallback, escalate_task).
Run local diagnostics for Codex, proxy ports, state paths, model allowlist, and concurrency (doctor).
Enforces local-first security: loopback-only web console, automatic read-only tasks, approval-gated write tasks in isolated Git worktrees, and no automatic commit/merge/push/publish or danger-full-access.
Allows delegating planning, review, debugging, complex coding, and executor tasks to OpenAI agents/models such as gpt-5.6-sol through configurable routing and model allowlists.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@LightWorker Split the refactoring into parallel tasks and approve the write ones via the console."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
LightWorker is a lightweight, local-first multi-agent task runner with no third-party Python runtime dependencies. It provides dual worker harness execution for both OpenAI Codex and ZCode / GLM CLI, persists the task DAG in SQLite, and uses an isolated Git worktree for write tasks.
Current release:
v0.8.0makes task state trustworthy: every task persists its real backend session id (codex thread / ZCode sessionId), restart reconciliation probes pid liveness instead of blanket-orphaning, and a reaper clears tasks whose worker process died without reporting — no more stuck "running" rows. It also passesZCODE_*runtime hints through to the ZCode CLI, restoring compatibility with ZCode 0.17+. It retains dual harness support (CodexWorker+ZCodeWorker) and the Codex-native subagent bridge introduced in v0.6.0. By default, LightWorker listens only on the local loopback address and does not automatically commit, merge, push, or publish; write tasks require approval and run in an isolated Git worktree. See CODEX_NATIVE_BRIDGE.md and README_CN.md.
Capability | What it does |
Dual Worker Harness | Native execution for both OpenAI Codex ( |
ZCode Auto-Detection | Zero-config discovery for standard ZCode installation paths: |
Persistent task DAG | SQLite WAL stores tasks, dependencies, events, PIDs, results, and worktree information |
Codex-native bridge | Durable native dispatch tickets, lease protection, native thread IDs, and host callbacks for |
Automatic decomposition and parallelism | Lead Codex generates a directed acyclic task graph; independent read-only Workers can run in parallel |
Reasoning-aware routing | Mechanical tasks go to DeepSeek V4 Flash by default; complex tasks use |
Approval and isolation |
|
Three control surfaces | CLI, Codex MCP, and the local Web Console share the same scheduler and state store |
Measurable cache optimization | Prompt Protocol v5, strict Cache Cohort v2 isolation, explicit Context Packs, cache-affinity scheduling, and verified warm-cache metrics |
Dual-gateway profiles | Named Planner, fast, deep, and review profiles can route through OpenCodex or CLIProxyAPI with explicit fallback and route audits |
Capability-aware routing | Tasks declare required capabilities (e.g. |
Scope-bound approvals | Each approval binds |
History management | The Web Console can purge terminated tasks with their events and usage records in one click |
Local-first security |
|
Related MCP server: AgentBraid
Boundary | Default behavior |
Web Console | Only the literal loopback addresses |
Read-only tasks | Can run automatically under |
Write tasks | Manual approval, using an isolated Git worktree |
User Codex configuration | Ignored by Workers by default, avoiding inheritance of MCP servers with external write access |
Git and external systems | Never automatically commits, merges, pushes, publishes, or grants |
See SECURITY.md for the full threat model and how to report vulnerabilities.
Python 3.11+
Git
Codex CLI or ZCode CLI (Auto-detected on Windows)
A working Codex / ZCode login or a configured model gateway
CLIProxyAPI/OpenCodex Proxy on the current machine (when using non-OpenAI models)
The local development verification environment is Python 3.13, Git 2.51, Codex CLI, ZCode CLI, and SQLite 3.51.
Install the CI-verified universal wheel directly from the v0.8.0 GitHub release:
python -m pip install https://github.com/ncepuee/LightWorker/releases/download/v0.8.0/lightworker-0.8.0-py3-none-any.whl
lightworker init
lightworker doctorSHA-256 checksums for release assets are listed in SHA256SUMS-v0.8.0.txt. When developing or auditing the source, you can install from a pinned tag:
git clone --branch v0.8.0 --depth 1 https://github.com/ncepuee/LightWorker.git
cd LightWorker
python -m pip install -e .You can run it directly after installation:
$env:LIGHTWORKER_HOME = "$env:LOCALAPPDATA\LightWorker"
lightworker init
lightworker doctormacOS / Linux:
export LIGHTWORKER_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/lightworker"
lightworker init
lightworker doctorFor a local CLIProxyAPI/OpenCodex setup, we recommend initializing LightWorker with an isolated Codex configuration:
lightworker init --force --isolated-codex `
--codex-base-url "http://127.0.0.1:10100/v1" `
--model-catalog "$env:USERPROFILE\.codex\opencodex-catalog.json"Submit a read-only DeepSeek V4 Flash investigation:
lightworker submit `
--workspace "/path/to/project" `
--kind explore `
--model "deepseek/deepseek-v4-flash" `
--run `
"Analyze the project structure and list the three modules that most need tests."Let Lead Codex decompose the task automatically:
lightworker orchestrate `
--workspace "/path/to/project" `
--mode auto_readonly `
--run `
"Find the cause of intermittent HTTP 500 errors in the login endpoint and provide an evidence-backed remediation plan."Example default routing in v0.8.0:
Task type | Default model |
Planner / design / review / debugging / complex coding |
|
Mechanical execution, formatting, and simple retrieval at |
|
Executor |
|
When a single task does not specify a model explicitly, routing is automatic based on reasoning effort: low uses deepseek/deepseek-v4-flash; medium/high/xhigh use gpt-5.6-sol. In other words, mechanical execution, formatting, and simple retrieval go to Flash, while design, planning, review, debugging, and complex coding go to OpenAI agents.
Model names and the allowlist can be configured in %LOCALAPPDATA%\LightWorker\config.toml.
Run this in the project directory:
lightworker webThis starts the local dashboard at http://127.0.0.1:8765/.
Release one task that is awaiting approval into the execution queue.
Inputs: task_id (required), approval_id (required), scope_digest (required).
Cancel a queued or active task and terminate its worker process tree.
Inputs: task_id (required).
Claim queued Codex-native tickets for this current host. For every ticket, call spawn_agent, then native_subagent_started. This is the real native bridge; it never runs codex exec as a fallback.
Inputs: host_id (required), limit, lease_seconds.
Queue up to the configured limit of already-decomposed worker tasks.
Inputs: tasks (required).
Queue one bounded worker task. Explore/review are read-only; execute uses an isolated git worktree and may require approval.
Inputs: objective (required), workspace (required), kind, mode, +17 more.
Check local Codex, proxy ports, state paths, model allowlist, and concurrency.
Inputs: no named parameters.
Create one budgeted read-only retry using a deeper worker profile. The original task remains unchanged.
Inputs: task_id (required), profile.
Return materialized cold/warm cache telemetry and target status without scanning event JSON.
Inputs: model, gateway, window_seconds.
Read append-only task events after an event cursor.
Inputs: task_id (required), limit, after_id.
Get one task, its dependencies, and structured result when available.
Inputs: task_id (required).
List every task belonging to an orchestration root.
Inputs: root_id (required).
List recent tasks, optionally filtered by status.
Inputs: limit, status.
Persist the terminal result returned by a native Codex subagent after wait_threads completes.
Inputs: status (required), task_id (required), lease_id (required), error, +1 more.
Write a bounded native-thread progress event and refresh its dispatch lease while waiting with wait_threads.
Inputs: task_id (required), lease_id (required), event_type (required), payload.
Acknowledge that the current Codex host spawned a native subagent for a claimed LightWorker ticket.
Inputs: task_id (required), lease_id (required), thread_id (required).
Queue a bounded Lead Codex planning run. It creates a dependency-aware task graph and automatically dispatches allowed child tasks.
Inputs: objective (required), workspace (required), mode, model, +5 more.
Clone a failed read-only task onto its configured fallback gateway. Never falls back automatically.
Inputs: task_id (required).
Wait up to 55 seconds for tasks to reach a terminal or approval state.
Inputs: task_ids (required), timeout_seconds.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 18 tools
Most tools have a distinct resource/action: delegation (delegate_task, delegate_batch, orchestrate), task lifecycle (approve/cancel/retry/escalate), and native subagent lifecycle are separated. Boundaries are mostly clear, though retry_fallback vs escalate_task and the multi-step native_* flow require careful reading.
Names are overwhelmingly snake_case and follow verb_noun for most operations (get_task, list_tasks, cancel_task, delegate_batch). Exceptions like doctor, orchestrate, and the native_subagent_* resource_event pattern are minor deviations rather than chaotic.
18 tools is slightly above the typical 3-15 range, but the orchestration domain is broad and each tool maps to a distinct lifecycle step or diagnostic. It is heavy but not obviously bloated.
The surface covers delegation, orchestration, task inspection/waiting/events, approval, cancellation, fallback/escalation, diagnostics, cache metrics, and native subagent lifecycle. Minor gaps like explicit approval rejection or lease release are workaroundable, and some workflow references external host tools (spawn_agent, wait_threads).
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.