codex-grok-orchestrator CLI / package: grok-worker 命令行 / 包名：grok-worker
Open-source orchestration framework 开源编排框架

Codex dispatches.
Grok executes.
Evidence decides. Codex 分发。
Grok 执行。
证据裁决。

A restrained boundary for repository work: the dispatcher scopes and reviews; Grok runs inside disposable clones under lifecycle control; only a verified three-file handoff can be accepted.

面向仓库任务的克制边界：调度器划定范围并审核；Grok 在 disposable clone 中、 受生命周期约束地执行；只有通过验证的三文件交接制品才可被接受。

View on GitHub Read the README
在 GitHub 查看 阅读 README

Public repo codex-grok-orchestrator · installable CLI grok-worker · Apache-2.0

公共仓库 codex-grok-orchestrator · 可安装 CLI grok-worker · Apache-2.0

Three roles, one boundary 三个角色，一条边界

Orchestration works when responsibilities stay separate. The worker never becomes the publisher.

职责分离，编排才可靠。Worker 永远不会变成发布者。

01 · Dispatcher

Codex / ACP

Scopes the task, sets permissions, reviews artifacts, and decides whether anything is integrated.

02 · Lifecycle

grok-worker

Creates the disposable clone, enforces capacity and cleanup rules, and requires verifiable evidence.

03 · Executor

Grok worker

Analyzes or implements inside the clone under an explicit profile—and stops at evidence, not merge.

01 · 调度器

Codex / ACP

划定任务与权限，审核制品，并决定是否合入任何变更。

02 · 生命周期

grok-worker

创建 disposable clone，执行容量与清理规则，并强制要求可验证证据。

03 · 执行者

Grok Worker

在明确配置下于克隆内分析或实现——止于证据，而非合并。

Architecture flow 架构流程

Source stays canonical. Work happens in isolation. Acceptance waits on verified artifacts.

源仓库始终为真相源。工作在隔离环境中发生。接受与否取决于已验证制品。

Dispatch

The coordinator issues a one-shot run or a named session with an explicit permission profile.

Isolate

grok-worker materializes a disposable clone; lifecycle metadata becomes the sole state authority.

Execute

Grok works inside the clone—analysis or implementation—without editing the source checkout.

Evidence

External artifacts are verified. Only then may a successful clone be reclaimed; the dispatcher reviews and decides.

分发

协调者发出一次性任务或命名会话，并附带明确的权限配置。

隔离

grok-worker 创建 disposable clone；lifecycle 元数据成为唯一状态权威。

执行

Grok 在克隆内进行分析或实现，不直接修改源仓库工作区。

证据

验证外部制品。成功克隆仅在验证通过后可回收；调度器负责审核并决定是否接受。

What makes it different 关键差异

  • Isolation first

    Every task runs in a disposable clone. The source repository remains the only project truth.

  • Lifecycle authority

    Progress files and completion events wake you up—they cannot fake success or authorize deletion.

  • Fail-closed cleanup

    Ambiguous paths, identity drift, and missing evidence keep directories; GC never guesses.

  • Configurable, not hard-locked

    Model and reasoning profile are explicit. Private dispatcher policy is not sold as a universal lock.

  • 先隔离

    每个任务在 disposable clone 中运行。源仓库始终是唯一的项目真相源。

  • 生命周期权威

    进度文件与完成事件用于唤醒观察——不能伪造成功，也不能授权删除。

  • 删除 fail-closed

    路径不明、身份漂移、证据不足时保留目录；GC 从不猜测。

  • 可配置，非硬锁

    模型与推理强度显式可配。私有调度策略不会被伪装成全局硬锁。

Verified three-file artifact contract 已验证的三文件制品契约

Success is reclaimable only after the external artifact directory passes verification.

只有外部制品目录通过验证后，成功任务才允许回收克隆。

changes.patch

Reviewable, replayable diff. Read-only work may produce a valid empty patch.

worker.log

Lifecycle, session provenance, and full agent output for audit.

verification.txt

Structured result, verification records, cleanup receipt, metrics, and hashes.

changes.patch

可审核、可重放的差异。只读任务可以是有效空补丁。

worker.log

生命周期、会话来源与完整 Agent 输出，便于审计。

verification.txt

结构化结果、验证记录、清理回执、指标与哈希。

Clone-local .grok-output/result.json is embedded into verification.txt—not a fourth external artifact.

克隆内 .grok-output/result.json 会嵌入 verification.txt——不是第四个外部制品。

One-shot quick start 一次性任务快速开始

Install the package, then run a bounded analysis task. Implementation mode uses the same shape.

安装包后执行一次有界分析任务。实现模式使用相同形态。 

uv tool install --force "git+https://github.com/MaxxxDong/codex-grok-orchestrator.git@v0.5.3"

grok-worker status --source /path/to/repository --json

grok-worker run \
  --source /path/to/repository \
  --mode analysis \
  --task-id public-release-audit \
  --prompt "Audit packaging and release readiness. Do not edit files."
uv tool install --force "git+https://github.com/MaxxxDong/codex-grok-orchestrator.git@v0.5.3"

grok-worker status --source /path/to/repository --json

grok-worker run \
  --source /path/to/repository \
  --mode analysis \
  --task-id public-release-audit \
  --prompt "检查打包与发布就绪情况；不要修改文件。"

Named sessions use session-start, session-followup, and session-finalize with a task manifest. See the repository README for full usage.

命名会话使用 session-start、 session-followup 与 session-finalize，并配合任务清单。 完整用法见仓库 README。

Safety boundary 安全边界

Workers produce evidence. They do not merge, push, publish, submit, or self-approve.

Worker 只交付证据，不合并、不推送、不发布、不提交外部事务、不自行批准自己的工作。

  • No provider credentials, OAuth state, or relay endpoints in the public core.
  • Workers allow at most 3 non-overlapping subagents; disable them explicitly when unnecessary.
  • Deletion protects the source, home, artifacts, shared cache, and disposable root.
  • Private overlays own competition gates, org approval chains, and personal paths.
  • 公共核心不包含服务商凭据、OAuth 状态或中转地址。
  • Worker 最多允许 3 个不重叠子代理；不需要时应显式关闭。
  • 删除保护源仓库、家目录、制品目录、共享缓存与 disposable 根目录。
  • 比赛 Gate、组织审批链与个人路径属于私有叠加层。

Introduction 介绍视频

A short overview of the orchestration boundary (Chinese narration).

编排边界的简短介绍（中文旁白）。

Media: assets/grok-worker-intro-zh-final.mp4 · poster assets/grok-worker-intro-poster.jpg

媒体：assets/grok-worker-intro-zh-final.mp4 · 海报 assets/grok-worker-intro-poster.jpg

Documentation 文档

Acknowledgements 致谢

The public boundary was informed by the thin integration approach in stdevMac/grok-in-codex and the orchestration/release discipline in Cjbuilds/Codex-Orchestration. No source code from either project is included.

公共边界参考了 stdevMac/grok-in-codex 的轻量接入思路，以及 Cjbuilds/Codex-Orchestration 的编排与发布纪律。未复制上述项目的任何源代码。

Start from the source 从源码开始

Clone the public repository, install grok-worker, and keep acceptance on the reviewer’s desk.

克隆公共仓库，安装 grok-worker， 把是否接受留在审核者一侧。

GitHub: MaxxxDong/codex-grok-orchestrator
GitHub：MaxxxDong/codex-grok-orchestrator