LightWorker

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 and 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 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:

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. 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 .

Quick Start

You can run it directly after installation:

$env:LIGHTWORKER_HOME = "$env:LOCALAPPDATA\LightWorker"
lightworker init
lightworker doctor

macOS / Linux:

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:

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	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:

lightworker web

This starts the local dashboard at http://127.0.0.1:8765/.