LightWorker
<p align="center">
<img src="lightworker/web/logo.svg" alt="LightWorker task graph converging into an execution core" width="112">
</p>
<h1 align="center">LightWorker</h1>
<p align="center">English | <a href="README_CN.md">中文</a></p>
<p align="center"><strong>Local-first multi-agent delegation and approval control for Codex and ZCode.</strong></p>
<p align="center">
<a href="https://openai.com/codex/"><img alt="ZCode & Codex Support" src="https://img.shields.io/badge/Dual_Harness-ZCode_%26_Codex-007ACC?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTEyIDJMMiA3bDEwIDUgMTAtNS0xMC01ek0yIDE3bDEwIDUgMTAtNS0xMC01LXRvLTUtMTB6bTAgLTRsMTAgNSAxMC01LTEwLTUtMTB6Ii8+PC9zdmc+&logoColor=white"></a>
<a href="https://chatglm.cn/"><img alt="GLM-5.3-Flash Agent used @0.8.0" src="https://img.shields.io/badge/GLM--5.3--Flash-Agent_used%400.8.0-2563EB"></a>
<a href="https://github.com/ncepuee/LightWorker"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ncepuee/LightWorker?logo=github&cacheSeconds=86400"></a>
</p>
<p align="center">
<a href="https://github.com/ncepuee/LightWorker/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ncepuee/LightWorker/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://github.com/ncepuee/LightWorker/releases/latest"><img alt="Release v0.8.0" src="https://img.shields.io/badge/Release-v0.8.0-31D0AA"></a>
<img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white">
<a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-31D0AA.svg"></a>
</p>
<p align="center">
<a href="#installation">Installation</a> ·
<a href="#quick-start">Quick Start</a> ·
<a href="#web-console">Web Console</a> ·
<a href="#codex-mcp">Codex MCP</a> ·
<a href="SECURITY.md">Security</a> ·
<a href="https://github.com/ncepuee/LightWorker/releases">Releases</a> ·
<a href="CONTRIBUTING.md">Contributing</a>
</p>
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.0` makes 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 passes `ZCODE_*` 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](docs/CODEX_NATIVE_BRIDGE.md) and [README_CN.md](README_CN.md).
## Core Capabilities
| Capability | What it does |
|---|---|
| Dual Worker Harness | Native execution for both OpenAI Codex (`CodexWorker`) and ZCode / GLM CLI (`ZCodeWorker`) with dynamic routing |
| ZCode Auto-Detection | Zero-config discovery for standard ZCode installation paths: `%ProgramFiles%` / `%LOCALAPPDATA%` on Windows, `/Applications/ZCode.app` or `~/Applications/ZCode.app` on macOS |
| 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 `spawn_agent` / wait results |
| 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 `gpt-5.6-sol` |
| Approval and isolation | `auto_readonly` runs read-only tasks automatically; write tasks wait for approval and enter an isolated Git worktree |
| 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. `web_search`); gateways that lack them are excluded up front and fail closed instead of silently degrading |
| Scope-bound approvals | Each approval binds `approval_id` plus a SHA-256 scope digest; a task spec that changes after approval is refused |
| History management | The Web Console can purge terminated tasks with their events and usage records in one click |
| Local-first security | `danger-full-access` is prohibited; user MCP servers are isolated by default; no automatic commit, merge, push, or publish |
## Secure Defaults
| Boundary | Default behavior |
|---|---|
| Web Console | Only the literal loopback addresses `127.0.0.1` / `::1` are allowed |
| Read-only tasks | Can run automatically under `auto_readonly` |
| 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 `danger-full-access` |
See [SECURITY.md](SECURITY.md) for the full threat model and how to report vulnerabilities.
## Requirements
- 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.
## Installation
Install the CI-verified universal wheel directly from the v0.8.0 GitHub release:
```bash
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 doctor
```
SHA-256 checksums for release assets are listed in [`SHA256SUMS-v0.8.0.txt`](SHA256SUMS-v0.8.0.txt). When developing or auditing the source, you can install from a pinned tag:
```bash
git clone --branch v0.8.0 --depth 1 https://github.com/ncepuee/LightWorker.git
cd LightWorker
python -m pip install -e .
```
## Quick Start
You can run it directly after installation:
```powershell
$env:LIGHTWORKER_HOME = "$env:LOCALAPPDATA\LightWorker"
lightworker init
lightworker doctor
```
macOS / Linux:
```bash
export LIGHTWORKER_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/lightworker"
lightworker init
lightworker doctor
```
For a local CLIProxyAPI/OpenCodex setup, we recommend initializing LightWorker with an isolated Codex configuration:
```powershell
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:
```powershell
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:
```powershell
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 | `gpt-5.6-sol` |
| Mechanical execution, formatting, and simple retrieval at `low` reasoning effort | `deepseek/deepseek-v4-flash` |
| Executor | `gpt-5.6-sol` |
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`.
## Web Console
Run this in the project directory:
```bash
lightworker web
```
This starts the local dashboard at `http://127.0.0.1:8765/`.
TDQS
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).