Subshell Docs

Codex

Run Codex as a Subshell agent.

Before you start

Install codex using the vendor instructions and authenticate it under the execution account. Ask an administrator to enable the harness under Settings → Server Settings → Plugins in the server dashboard's sidebar. Follow Install an agent CLI to confirm detection on the target node.

Launch

  1. In the server dashboard's sidebar, choose Subshells, select New subshell, and choose Codex.
  2. Select a preset or configure the supported launch settings.
  3. Choose the target node and an existing project directory.
  4. Launch and confirm that the CLI opens normally.

The plugin detects codex through PATH and its known locations. CODEX_PATH can identify the binary explicitly in the execution environment. Before changing that override, see Files and paths for configuration locations and service-environment guidance.

MCP and session behavior

Subshell supplies MCP configuration through per-launch CLI settings. You don't need to register the Subshell MCP server globally for this harness. The built-in plugin declares MCP, settings, and subagent monitoring capabilities; it doesn't declare automatic conversation resumption or attention hooks.

Subshell runs the real CLI rather than proxying its provider API. Provider configuration, usage limits, and CLI-specific permissions remain the agent's own settings.

If Codex reports that Subshell MCP failed, open /mcp and follow MCP troubleshooting. In particular, having pane credentials in the shell doesn't guarantee that Codex forwards them to its MCP child.

Subagent monitoring hooks

Subshell adds hooks labeled Subshell subagent monitoring when it launches Codex. They report subagent identifiers, types, task names, and start/stop events to your Subshell server so active subagents appear beneath their parent in the sidebar. Subshell shows each child's status only; use Codex's own /subagents picker to switch views. The reporter doesn't send prompts or transcripts.

In Codex, open /hooks to review the SessionStart, SubagentStart, SubagentStop, and PostToolUse hooks and trust them if you want monitoring enabled. Codex may ask you to review them again when their definitions change. Leaving them untrusted or disabled prevents monitoring; you can still use Codex normally.

Subshell supplies these hooks as per-run config overrides. Codex replaces its own hooks.* table for that run, so a personal PostToolUse auditor won't run in a Subshell-launched Codex. The PostToolUse entry is only the spawn-task-name reporter; launch Codex outside Subshell if you rely on that auditor.

Next steps

Read MCP configuration, Presets, and Agent and launch errors.

Edit on GitHub

Last updated on

On this page