# Direct Startup Mode vs Shared Session Mode in the Codex Plugin: A Complete Guide

> Explore direct startup mode vs shared session mode in the Codex plugin. Understand the core differences and choose the right runtime for your needs.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-08-04

---

**The Codex plugin supports two runtime modes: direct startup mode launches a fresh app-server process for every command, while shared session mode maintains a persistent broker-managed session that subsequent commands reuse.**

The `openai/codex-plugin-cc` repository implements two distinct strategies for running the Codex app-server. These modes determine how the plugin handles session lifecycle, state persistence, and performance characteristics. Understanding which mode your plugin is using—and when to prefer one over the other—is essential for building reliable Codex-powered workflows.

## How Direct Startup Mode Works

In **direct startup mode**, the plugin spawns a new Codex app-server process for each command execution. The main entry point in `codex-companion.mjs` handles this directly without delegating to any intermediate broker.

```bash

# Each command starts a completely fresh Codex session

$ /codex:review "Check this code for bugs"
$ /codex:task "Refactor the authentication module"
$ /codex:status

# → Session runtime: direct startup

```

The `sessionRuntime.mode` field in the JSON status payload is set to `"direct"`, which renders as `Session runtime: direct startup` in human-readable output. This mode is the default when no broker endpoint is configured or when the plugin cannot locate broker configuration.

According to the test suite in `tests/runtime.test.mjs` (lines 44-45), the direct mode is verified by checking that no broker is present and that the status command returns the expected runtime identifier.

### Key Characteristics of Direct Startup

- **Full isolation**: Every command runs in a completely separate process with no shared state
- **No persistence**: Thread IDs, sub-agent messages, and other session state are discarded after each command
- **Higher latency**: Process startup overhead applies to every invocation
- **Simplicity**: No configuration required; works out of the box

## How Shared Session Mode Works

**Shared session mode** relies on a **lazy broker** implemented in `plugins/codex/scripts/lib/broker-lifecycle.mjs`. This subsystem creates and maintains a persistent Codex session that survives across multiple plugin commands.

```bash

# First command initializes the broker-managed session

$ /codex:review --background

# Subsequent commands reuse the existing session

$ /codex:status

# → Session runtime: shared session

$ /codex:task --resume-last "Continue where we left off"

```

The `sessionRuntime.mode` field returns `"shared"` when the broker is active, displaying `Session runtime: shared session` in status output. The test at `tests/runtime.test.mjs` lines 2209-2211 validates this behavior by checking broker detection.

### Key Characteristics of Shared Session

- **State persistence**: Thread IDs, conversation history, and sub-agent context remain available
- **Lower latency**: Subsequent commands skip process initialization
- **Feature enablement**: Powers background jobs (`--background`), rescue operations, and thread resumption (`--resume-last`)
- **Shared side effects**: All commands in the session can see and modify the same Codex state

## Comparing the Two Modes

| Aspect | Direct Startup Mode | Shared Session Mode |
|--------|---------------------|---------------------|
| **Process lifecycle** | New process per command | Single persistent process |
| **Session runtime value** | `"direct"` | `"shared"` |
| **Primary implementation** | `codex-companion.mjs` | `broker-lifecycle.mjs` |
| **Startup latency** | Higher (process spawn) | Lower (reuse existing) |
| **State isolation** | Complete | None—shared across commands |
| **Use cases** | One-off reviews, simple tasks | Multi-step workflows, background jobs |
| **Configuration** | Default, no setup required | Requires lazy broker detection |

## When to Use Each Mode

### Choose Direct Startup Mode When:

- You need **guaranteed isolation** between unrelated tasks
- Running simple, **stateless one-off commands**
- Debugging Codex behavior (clean slate per invocation)
- No broker infrastructure is available

### Choose Shared Session Mode When:

- Building **multi-step workflows** that reference previous interactions
- Using **background execution** (`--background`) or **rescue** features
- Running **`codex:transfer`** or **`--resume-last`** operations
- Minimizing latency for a sequence of related commands

## Detecting Your Current Mode

The `status` command reveals which mode is active:

```bash
$ /codex:status

```

**Direct startup output:**

```

Session runtime: direct startup

```

**Shared session output:**

```

Session runtime: shared session

```

For programmatic detection, parse the JSON status payload and inspect `sessionRuntime.mode`. The `tests/status.test.mjs` file contains reference assertions for both formats.

## Summary

- **Direct startup mode** launches isolated, short-lived Codex processes—ideal for simple, independent tasks.
- **Shared session mode** maintains a persistent broker-managed session—essential for workflows requiring state continuity.
- The `broker-lifecycle.mjs` module implements the lazy broker that enables shared sessions, while `codex-companion.mjs` orchestrates direct startup.
- Mode detection is available via `/codex:status`, which reports either `"direct"` or `"shared"` in the `sessionRuntime.mode` field.

## Frequently Asked Questions

### How do I switch from direct startup to shared session mode?

Shared session mode activates automatically when a lazy broker is detected in your environment. No explicit configuration is required—simply ensure your broker endpoint is reachable, and the plugin will delegate to `broker-lifecycle.mjs` instead of spawning isolated processes.

### Can I force direct startup even when a broker is available?

The plugin defaults to shared session mode when a broker is detected. To guarantee isolation, you would need to disable or disconnect the broker endpoint, causing `codex-companion.mjs` to fall back to direct startup. The test suite at `tests/runtime.test.mjs` line 44 demonstrates this fallback behavior.

### What happens to shared session state if the broker crashes?

Session state is held in the broker process. If the broker terminates unexpectedly, the shared session is lost and subsequent commands will either fail or trigger creation of a new broker-managed session. The `codex:transfer` command can mitigate this by moving state to a stable destination before broker termination.

### Does shared session mode affect security or permissions?

Both modes execute with the same user permissions. However, shared session mode carries **state visibility risks**: commands executed by different users or in different contexts could access the same thread IDs and conversation history if they share a broker instance. Use direct startup mode when strict isolation between security contexts is required.