@ever-works/codex-plugin

Full pipeline plugin that delegates work generation to the Codex CLI. A single Codex session researches, creates, and updates work item JSON files inside a temporary workspace.

Plugin metadata

Pipeline Steps

The plugin runs 6 sequential steps:

During step 3, a taxonomy watcher monitors the workspace for new item files and keeps _meta/ taxonomy files (categories, tags, brands) in sync in real time. Progress is reported per item as files appear.

Authentication

Codex supports two authentication modes:

API Key

Provide an OpenAI API key in plugin settings (apiKey field).

Get one from platform.openai.com/account/api-keys.

Local Codex Auth

If no API key is configured, the plugin can use local Codex CLI auth stored in a managed per-user CODEX_HOME. Authenticate via the onboarding wizard or manually:

codex login

The plugin materializes an isolated CODEX_HOME for each Ever Works user under its managed temp work, so local Codex auth does not rely on a shared ~/.codex/auth.json.

The onboarding UI provides a 3-step flow: choose auth mode, configure credentials, and verify the connection.

Settings

Supported Models

• GPT-5.4 (default) - 400k context
• Codex Mini Latest - 200k context
• GPT-5.2 Codex - 400k context

Form Schema

The plugin provides a user-facing form with two configurable fields:

Prompt System

Prompts are managed through a prompt facade (e.g., Langfuse). When no external prompt is found, hardcoded defaults are used as fallback.

Prompt keys:

• codex.system - System prompt template
• codex.user - User prompt template

Both support variable substitution for work context, existing items, categories, tags, and brands.

Binary Management

The plugin automatically downloads and caches the Codex CLI binary:

• Binaries are cached in /tmp/codex-generator/bin/
• Supports Linux (x64/arm64) and macOS (x64/arm64)
• Falls back to a system-installed codex command if download fails
• Default CLI version: 0.120.0

Error Handling

• Non-zero exit codes: Treated as soft warnings. If items were still produced, the result succeeds with warnings attached.
• Sandbox write blocks: Detected and logged, but never retried with sandbox bypass on their own. The detector reads Codex's stdout/stderr, which is model-produced text that injected content (a fetched page, a README) can steer, so it cannot be allowed to escalate a run to --dangerously-bypass-approvals-and-sandbox. Bypass happens only when the operator explicitly enables unsafeBypassSandbox (then every run starts bypassed). See Sandbox bypass.
• Structured output recovery: If Codex completes without writing item files, the plugin attempts a second pass using --output-schema and --output-last-message to recover structured output.
• Masked secrets: The getRealSecret helper filters out UI placeholder values (••••) before using credentials.

Project Structure

src/
  codex.plugin.ts          # Main plugin class (IPlugin, IPipelinePlugin, IFormSchemaProvider, ILocalAuthProvider)
  types.ts                 # Step IDs, constants
  steps.ts                 # Pipeline step definitions
  form-schema.ts           # Form fields, groups, validation
  prompt-keys.ts           # Prompt facade keys
  device-auth.ts            # Device auth flow (codex login --device-auth)
  index.ts                 # Public exports
  prompt/
    system-prompt.ts       # Default prompts and variable builders
  utils/
    binary-manager.ts      # CLI binary download and caching
    pipeline-helpers.ts    # State management, auth resolution, progress reporting
    process-runner.ts      # Codex CLI subprocess execution
    workspace-manager.ts   # Workspace I/O (create, seed, read, cleanup)
    screenshot-capture.ts  # Screenshot facade integration
    taxonomy-sync.ts       # Merge new categories/tags/brands into _meta files
    taxonomy-watcher.ts    # Filesystem watcher for live taxonomy sync
    platform.ts            # Platform detection helpers
    subprocess-env.ts      # Environment variable setup for subprocesses
scripts/
  smoke-codex.mjs          # Manual smoke test script

Development

# Build
pnpm build

# Type-check
pnpm type-check

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage

Sandbox bypass

Codex runs inside its own sandbox unless told otherwise. Two paths can run it with --dangerously-bypass-approvals-and-sandbox (full host access, no approvals):

• Generation pipeline — only when the operator sets unsafeBypassSandbox: true (hidden setting, default false). The plugin no longer escalates on its own when Codex's output says writes were blocked: that output is model text, and a prompt-injected model could print exactly those phrases. A declined escalation is logged as a warning; structured-output recovery still runs, sandboxed.
• Code-edit path (executeCodeEdit) — always passes the bypass flag today. It edits a workspace the platform provisioned for the run and needs unrestricted writes there. Treat any host running code-edit as giving the Codex process the plugin's own OS privileges: run it in a container/VM with no credentials or networks it should not reach. This behaviour is unchanged and documented here so it is a known, reviewed trade-off.

Smoke Test

Validate real Codex CLI integration locally:

pnpm smoke

For hosts requiring sandbox bypass:

CODEX_SMOKE_BYPASS_SANDBOX=1 pnpm smoke

Requires either OPENAI_API_KEY in the environment or local Codex auth (codex login).

Troubleshooting

Documentation

• Ever Works documentation
• Ever Works repository
• Plugin system
• Codex CLI homepage
• OpenAI API keys

License

AGPL-3.0