The codex_local adapter runs OpenAI’s Codex CLI locally. It supports session persistence via previous_response_id chaining and skills injection through the global Codex skills directory.

​
Prerequisites

  • Codex CLI installed (codex command available)
  • OPENAI_API_KEY set in the environment or agent config

​
Configuration Fields

FieldTypeRequiredDescription
cwdstringYesWorking directory for the agent process (absolute path; created automatically if missing)
modelstringNoModel to use
promptTemplatestringNoPrompt used for all runs
envobjectNoEnvironment variables (supports secret refs)
timeoutSecnumberNoProcess timeout (0 = no timeout)
graceSecnumberNoGrace period before force-kill
dangerouslyBypassApprovalsAndSandboxbooleanNoSkip safety checks (dev only)

​
Session Persistence

Codex uses previous_response_id for session continuity. The adapter serializes and restores this across heartbeats, allowing the agent to maintain conversation context.

​
Skills Injection

The adapter symlinks DarkDuck skills into the global Codex skills directory (~/.codex/skills). Existing user skills are not overwritten.
When DarkDuck is running inside a managed worktree instance (DARKDUCK_IN_WORKTREE=true), the adapter uses a worktree-isolated CODEX_HOME so runtime state does not leak across checkouts.
For manual local CLI usage outside heartbeat runs: 
pnpm darkduck agent local-cli codexcoder --company-id <company-id>
This installs any missing skills, creates an agent API key, and prints shell exports to run as that agent.

​
Instructions Resolution

If instructionsFilePath is configured, DarkDuck reads that file and prepends it to the stdin prompt sent to codex exec on every run. This is separate from any workspace-level instruction discovery that Codex itself performs. DarkDuck does not disable Codex-native repo instruction files, so a repo-local AGENTS.md may still be loaded in addition to the DarkDuck-managed agent instructions.

​
Environment Test

The environment test checks:
  • Codex CLI is installed and accessible
  • Working directory is absolute and available
  • Authentication signal (OPENAI_API_KEY presence)
  • A live hello probe to verify the CLI can actually run
Use the “Test Environment” button in the agent configuration UI before enabling heartbeats. This catches configuration issues (missing CLI, bad working directory, missing API key) before they cause failed runs.