Skip to content
AI OutfitterAI OutfitterAI Outfitter

DeepWork on Codex

Synced from deepwork/docs/codex.md. The repository is the source of truth.

DeepWork ships a Codex plugin that provides the deepwork_* tool surface, the bundled skills, and the DeepSchema write-feedback hook.

The Pi path is unchanged. Pi keeps its native pi.registerTool() tools and does not go through MCP.

Install

Section titled “Install”
Terminal window
npm install -g @ai-outfitter/deepwork
codex plugin marketplace add ai-outfitter/deepwork
codex plugin add deepwork@ai-outfitter

The npm install is required, not optional: it puts deepwork-mcp on PATH, and a PATH command is the only launcher Codex can resolve (see below).

Start a new Codex session afterwards. Bundled skills and tools become available only in sessions started after the install.

The plugin launches the server as a bare command:

{ "command": "deepwork-mcp" }

No path, and no cwd key. Both omissions are deliberate.

Why the launcher is a PATH command

Section titled “Why the launcher is a PATH command”

This is the only form that works. Measured against codex-cli 0.145.0:

args cwd Server starts process.cwd()
relative "." yes plugin root — wrong
relative omitted no —
absolute omitted yes your project — but no committed manifest can know the path
PATH command omitted yes your project

Codex expands no variables in a plugin MCP command. ${CLAUDE_PLUGIN_ROOT} and ${PLUGIN_ROOT} are both passed through literally and the server fails with No such file or directory. Setting cwd to "." makes the server start, but Codex then hands it the plugin directory as the working directory, and DeepWork resolves your project from the working directory.

Configuration

Section titled “Configuration”

Codex passes a plugin MCP server almost nothing. The server receives only HOME, LANG, LOGNAME, PATH, SHELL, TERM, USER, and whatever the plugin manifest declares in an env block. Variables exported in your shell do not reach it.

That means these are ignored on Codex unless you declare them in the manifest:

  • DEEPWORK_ADDITIONAL_JOBS_FOLDERS
  • DEEPWORK_STANDARD_JOBS_DIR
  • DEEPWORK_ADDITIONAL_SCHEMAS_FOLDERS
  • DEEPWORK_STANDARD_SCHEMAS_DIR
  • DEEPWORK_PROJECT_DIR
  • DEEPWORK_SESSION_ID

Without them you get the seven bundled standard_jobs/ workflows and nothing else. To use your own job library, add an env block to the installed plugin’s mcp-servers.codex.json:

{
  "mcpServers": {
    "deepwork": {
      "command": "npx",
      "args": ["-y", "-p", "@ai-outfitter/deepwork", "deepwork-mcp"],
      "env": { "DEEPWORK_ADDITIONAL_JOBS_FOLDERS": "/absolute/path/to/jobs" }
    }
  }
}

Absolute paths are required; the block is static and cannot reference your shell.

Hooks

Section titled “Hooks”

The DeepSchema write-feedback hook is at hooks/hooks.json and matches Write|Edit|MultiEdit|apply_patch. Codex routes edits through apply_patch and accepts Edit and Write as aliases for it.

Codex does not trust plugin hooks on install. It skips them until you review and trust the definition, so DeepSchema feedback is not active on first use.

Session state

Section titled “Session state”

DeepWork keys workflow state by session ID. Codex exposes no session identifier to an MCP server, so the server derives a stable ID from the project path. A workflow therefore stays reachable across sessions and codex resume rather than being stranded. Set DEEPWORK_SESSION_ID in the manifest env block to override.

Known gaps

Section titled “Known gaps”

These are not bridged, and each is Pi-only today:

  • Session-context restoration and stale-state cleanup on session shutdown.
  • Post-commit review reminders.
  • Pi-subagent review autolaunch with DEEPWORK_REVIEW_PASSED marker harvesting. /review instead asks the agent to run the tasks itself and call deepwork_mark_review_as_passed.