@meego-harness/codex-worker

Standalone Codex CLI worker bridge for meego-harness.

For most users, prefer @meego-harness/worker-cli as the primary entrypoint and install/manage this worker through meego-harness-worker. This package still supports direct standalone use.

It logs into a WorkerServerSDK endpoint as a coder worker, executes tasks through the local codex CLI, and reuses one Codex thread per harness contextId.

What You Need First

Before installing this package, make sure all of the following are already true:

1. Node.js and pnpm are available.
2. The Codex CLI is already installed separately and codex --help succeeds in your shell.
3. A target worker server is already running. Example: the local playground exposes ws://127.0.0.1:3000/workers.
4. You already have an absolute workspace directory on disk. Example: /workspace-root.

If any one of those is missing, setup or start will fail.

Command Summary

meego-codex-worker setup
meego-codex-worker setup --json --server-url ws://127.0.0.1:3000/workers --email [email protected] --worker codex-worker-1 --capability-summary "Handles TypeScript work" --workspace /workspace-root --permission-preset default --model gpt-5.4 --reasoning-effort high
meego-codex-worker list --json
meego-codex-worker doctor --json
meego-codex-worker start --worker <workerId> [--tmux] [--codex-shell]
meego-codex-worker stop --worker <workerId>
meego-codex-worker stop-all
meego-codex-worker enable --worker <workerId>
meego-codex-worker disable --worker <workerId>
meego-codex-worker uninstall --worker <workerId>

Install

Install into another project

pnpm add @meego-harness/codex-worker
pnpm exec meego-codex-worker setup

Use pnpm exec when the package is installed locally in the current project.

Install from this monorepo

The binary entrypoint loads dist/cli.js, so you must build the package first.

pnpm install
pnpm --filter @meego-harness/codex-worker build
pnpm --filter @meego-harness/codex-worker exec meego-codex-worker setup

Optional global install

pnpm add -g @meego-harness/codex-worker
meego-codex-worker setup

Enable And Configure A Worker

setup is the first enable step. It writes a local config file and marks the worker as enabled.

For automation and worker-cli, setup also supports non-interactive flags plus --json. Pass --codex-shell during setup to persist shell-based Codex invocation for that worker.

pnpm exec meego-codex-worker setup

setup asks for these values:

| Prompt | Required | What to enter | |---|---|---| | Worker Server URL | Yes | The websocket worker endpoint, for example ws://127.0.0.1:3000/workers | | Worker Email | Yes | Stable worker identity email, for example [email protected] | | Worker ID | Yes | Stable worker id, for example codex-worker-1 | | Capability Summary | Yes | Short summary shown to managers and dashboard | | Default Workspace | Yes | Existing absolute directory path. Relative paths are rejected. | | Default Permission Mode | Yes | safe, default, or full-access | | Default Model | Yes | use-codex-default or a pinned model | | Default Reasoning Effort | Yes | use-codex-default, low, medium, high, or xhigh | | Add a repo mapping? | Optional | Whether to pin specific repo names to specific absolute directories |

Example setup session values:

Worker Server URL:      ws://127.0.0.1:3000/workers
Worker Email:           [email protected]
Worker ID:              codex-worker-1
Capability Summary:     Handles TypeScript and README updates
Default Workspace:      /workspace-root
Default Permission Mode: default
Default Model:          gpt-5.4
Default Reasoning Effort: high
Repo Mapping:
  repo = meego-harness
  cwd  = /workspace-root/meego-harness

Start The Worker

After setup, start the worker with the same workerId:

pnpm exec meego-codex-worker start --worker codex-worker-1
pnpm exec meego-codex-worker start --worker codex-worker-1 --tmux
pnpm exec meego-codex-worker start --worker codex-worker-1 --codex-shell

--tmux 在当前环境不存在 tmux 时会自动回退到前台运行。 --codex-shell uses the user's shell to run the codex command, so shell aliases or functions can be honored. Without it, the worker runs the codex executable directly.

可通过以下方式停止后台会话：

pnpm exec meego-codex-worker stop --worker codex-worker-1

也可一次性停止全部 Codex worker 后台会话：

pnpm exec meego-codex-worker stop-all

If you installed globally, drop pnpm exec.

What start does:

1. Verifies that the local codex binary is callable.
2. Loads ~/.meego-harness/codex-worker/<workerId>.json.
3. Refuses to start if that worker is disabled.
4. Connects to the configured serverUrl.
5. Logs in as role coder.
6. Waits for tasks and runs them through codex exec.

First Login Behavior

If the target worker server enables device authorization, the first login can stay pending until someone approves it.

After that first approval, the worker client reuses the local device identity automatically and completes login through challenge-response signing. The device identity is stored under:

~/.meego-harness/worker-device-identities/<hash>.json

Disable A Worker

Disable prevents future start calls from succeeding until you enable the worker again.

pnpm exec meego-codex-worker disable --worker codex-worker-1

To enable it again:

pnpm exec meego-codex-worker enable --worker codex-worker-1

Important:

• disable changes local config only.
• disable does not kill an already-running process.
• If the worker is already running, stop that process as well, for example with Ctrl+C or by stopping your process manager.

Uninstall A Worker

uninstall removes the local worker installation state for one configured worker:

pnpm exec meego-codex-worker uninstall --worker codex-worker-1

This removes:

• ~/.meego-harness/codex-worker/<workerId>.json
• ~/.meego-harness/codex-worker/<workerId>.state.json
• The persisted worker device identity under ~/.meego-harness/worker-device-identities/

Then remove the package itself:

pnpm remove @meego-harness/codex-worker

If you installed globally:

pnpm remove -g @meego-harness/codex-worker

Repo Routing Rules

Task routing is driven by task.metadata.repo.

• If task.metadata.repo is absent, the worker runs in defaultWorkspace.
• If repoMappings is empty, the worker infers <defaultWorkspace>/<repo>.
• If repoMappings contains at least one entry, every incoming repo must be explicitly mapped.
• If the resolved directory does not exist, the task fails immediately instead of silently falling back.

Metadata Supported By The Worker

The worker reads these optional task metadata fields on first use of a contextId:

| Metadata key | Type | Meaning | |---|---|---| | repo | string | Selects the working directory | | codexReasoningEffort | string | One of low, medium, high, xhigh | | codexPlanMode | boolean | Prepends a planning-only preamble on the first message in that context |

Once a context is bound, later conflicting repo or reasoning metadata for the same contextId is ignored.

Local Files Written By This Package

Config file:

~/.meego-harness/codex-worker/<workerId>.json

Per-context state file:

~/.meego-harness/codex-worker/<workerId>.state.json

The state file stores the mapping from harness contextId to:

• resolved cwd
• pinned repo
• reused Codex threadId
• pinned reasoning effort
• plan mode flag

Operational Notes

• One Codex thread is reused per harness contextId.
• safe, default, and full-access map to Codex sandboxes read-only, workspace-write, and danger-full-access.
• Task cancellation aborts the in-flight Codex process.
• The worker role is fixed to coder.