# DeepWork on Codex

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

```bash
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:

```json
{ "command": "deepwork-mcp" }
```

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

## 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

**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`:

```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

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

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

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`.