Skip to content
, ,

Codex CLI Side Chats: New Terminal Workspace Guide (0.168 and 0.169)

9–14 minutes
Excited woman in a green hoodie in a dark studio holding a CODEX card, hook: Side chat tabs in Codex CLI

OpenAI shipped Codex CLI 0.168 and 0.169 on November 13, 2026. Together they add a new terminal workspace with side-chat tabs, a model provider picker, a diagnostic ZIP shortcut and a safer default for codex exec.

This guide shows you how to update, which config.toml lines turn each feature on, and what the new --trust rule means for your scripts.

TLDR

  • Update: run npm install -g @openai/codex@0.169.0, then check with codex --version.
  • Side chats: set tui_workspace = true under [features] to get side-chat tabs next to the main chat. Saved local side chats come back after a restart.
  • Providers: add or edit custom model providers from the terminal and pick a default for new chats under Sessions, then Model providers.
  • Security: codex exec now keeps project config and MCP servers off in untrusted folders. Pass --trust to save trust.
  • Extras: Ctrl+S saves a diagnostic ZIP, animated GIF image generation, audio attachments and OSC 777 notifications.

What’s New in Codex CLI 0.168 and 0.169

Both versions landed on the same day. Version 0.168 brought the workspace and the provider list. Version 0.169 polished the workspace, added search to the agent command center and fixed the trust gap in codex exec.

If you are new to Codex, start with my OpenAI Codex guide first. Here is everything that changed, in one table.

Feature Version How to use it
Side conversation beside the main chat 0.168 features.tui_workspace
Multiple side-chat tabs (keyboard or mouse) 0.169 Same workspace, opt-in
Saved local side chats reopen after restart 0.169 Automatic in the workspace
Pane zoom 0.168 Leader key, then z
Browse providers and set a default 0.168 Sessions, then Model providers
Add or edit custom providers from the terminal 0.169 Also offered during sign-in
Device-code sign-in for supported gateways 0.169 During provider sign-in
Search older tasks in the agent command center 0.169 Matches task name, prompt preview or folder
Collapse turn details in the transcript 0.169 Full-screen transcript view
Diagnostic ZIP 0.169 Ctrl+S in the report editor
Opt-in Cloud connection (images, model, reasoning effort, archive and restore) 0.169 macOS and Linux
Animated GIF generation and editing 0.168 features.image_generation_animation
Audio attachments 0.168 Audio-capable models only
OSC 777 notifications 0.168 tui.notification_method = "osc777"
Image previews in tmux (Ghostty, Kitty) 0.168 tmux allow-passthrough all
features.multi_agent deprecated 0.168 Use agents.enabled
Untrusted folders stay locked in codex exec 0.169 Add --trust to save trust

How to Update Codex CLI

The changelog lists an npm install command for each release. The steps below work on macOS, Linux and Windows.

  1. Close running sessions. Quit any open Codex terminal sessions so the binary is not in use.
  2. Install the new version. Run npm install -g @openai/codex@0.169.0. Use @latest instead of the version number if you always want the newest build.
  3. Check the version. Run codex --version and confirm it prints 0.169.0 or newer.
  4. Back up your config. Copy ~/.codex/config.toml before you change it. A typo in TOML can stop Codex from starting.
  5. Remove deprecated keys. If your config sets multi_agent under [features], swap it for agents.enabled (shown below).
npm install -g @openai/codex@0.169.0
codex --version

Note: If you installed Codex with Homebrew or another package manager, upgrade it with that same tool. Mixing npm and Homebrew installs can leave an old binary first on your PATH.

How to Turn On Side-Chat Tabs

Codex already had the /side slash command. It opens a short-lived side chat forked from your current chat, so you can ask a quick question without derailing the main task.

The new terminal workspace puts that side conversation in its own pane next to the main chat. In 0.169 you can open several side chats as tabs.

Step 1: Enable the workspace flag

The workspace is opt-in. Add this to ~/.codex/config.toml and restart Codex.

[features]
tui_workspace = true

Step 2: Open and use side chats

  1. Start a side chat. Type /side in the main chat. You can add a question inline, for example /side Check whether this plan has an obvious risk.
  2. Switch tabs. Move between side-chat tabs with the keyboard or click them with the mouse.
  3. Resize panes. Drag the divider between the main chat and the side pane.
  4. Zoom a pane. Press your leader key, then z, to zoom the focused pane.
  5. Come back later. Saved local side chats reopen after you restart Codex, so you do not lose a useful thread.

Tip: The leader key is set in /keymap, and its default was Ctrl+X when it arrived in 0.163. Run /keymap to check or change yours before you try the zoom shortcut.

What side chats are good for

  • Quick checks: ask “what does this error mean?” while the main task keeps its context clean.
  • Plan reviews: ask a second opinion on a plan before you approve it.
  • Research: look up an API or flag without filling the main transcript.

A side chat keeps its transcript separate from the parent. You cannot open a side chat inside another side chat, and it is not available during review mode.

How to Add a Custom Model Provider

Version 0.168 added a model provider list under Sessions, then Model providers, where you can set the default provider for new chats. Version 0.169 lets you add or edit custom providers from the terminal, including during sign-in.

You can also set providers up by hand in config.toml. Here are the main keys from the official config reference.

Key What it does
model_provider The default provider ID. Defaults to openai.
name Display name for the provider.
base_url The API base URL.
env_key Environment variable that holds the API key.
auth table A command that prints a token. Do not combine it with env_key.
wire_api Protocol. responses is the only value and the default.
http_headers Static headers sent with each request.
request_max_retries HTTP retry count. Default 4.

Example: OpenRouter

OpenRouter’s own Codex guide recommends a command-based auth block. With a plain env_key, Codex does not fetch the OpenRouter model catalog, and non-OpenAI models show an “Unknown model” warning.

  1. Set your key. On macOS or Linux, add export OPENROUTER_API_KEY="sk-or-..." to your shell profile. On Windows, run setx OPENROUTER_API_KEY "sk-or-..." and restart Codex fully.
  2. Add the provider. Paste the block below into ~/.codex/config.toml.
  3. Pick the model. Set model to a model ID from OpenRouter. The example uses the one in OpenRouter’s guide.
  4. Confirm. Start Codex and run /status to see the active model and provider.
model_provider = "openrouter"
model = "~openai/gpt-sol-latest"

[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"

[model_providers.openrouter.auth]
command = "sh"
args = ["-c", "echo $OPENROUTER_API_KEY"]

On Windows, swap the auth block for this one:

[model_providers.openrouter.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:OPENROUTER_API_KEY"]

For pricing and free models, see my OpenRouter guide.

Example: Ollama (local)

Ollama and LM Studio are built-in providers. Their IDs (ollama, lmstudio, openai) are reserved, so you cannot redefine them. The simplest route is the --oss flag.

# config.toml
oss_provider = "ollama"   # or "lmstudio"

Then run codex --oss. If oss_provider is unset, Codex asks you which local provider to use. You can also pick one per run with --local-provider.

If you prefer a custom entry, give it a new ID. This is the example from the official docs:

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

Need a model to run? My list of the best Ollama models covers good picks by GPU size.

Warning: Profiles changed earlier this year. Since Codex 0.134.0, [profiles.<name>] tables and the top-level profile = "..." selector are no longer supported. Use a separate file such as ~/.codex/deep-review.config.toml and run codex --profile deep-review.

The New Trust Rule for codex exec

This is the change most likely to affect CI scripts. Codex only loads project-level .codex/ layers, such as .codex/config.toml and project MCP servers, when a folder is trusted.

Version 0.169 closes a gap here. codex exec now keeps project config and MCP servers disabled in untrusted folders, even with --sandbox workspace-write.

Why it matters

  • Cloned repos: a repo you just cloned could ship a .codex/config.toml that adds an MCP server or changes settings.
  • Headless runs: codex exec runs without a person watching, so a silent config change is riskier.
  • Clear intent: you now trust a folder on purpose, not by accident.

How to trust a folder

  1. Check the repo first. Read any .codex/ folder and AGENTS.md in the project before you trust it.
  2. Run once with trust. Add --trust to codex exec or codex review. This saves trust for the project.
  3. Or set it in config. Add a projects entry in your user-level config, as below.
codex exec --trust "run the test suite and fix failures"
# ~/.codex/config.toml
[projects."/home/you/code/my-app"]
trust_level = "trusted"   # or "untrusted"

Warning: Do not add --trust to a CI job that runs on pull requests from forks. Anyone could then add a project config or MCP server that your runner would load.

Other New Features Worth Knowing

Search older tasks in the agent command center

The agent command center (/agents or codex agents) now has search. It matches the task name, the prompt preview or the working folder. My agent command center guide covers the rest of that view.

Ctrl+S diagnostic ZIP

In the terminal report editor (part of the /feedback flow), press Ctrl+S to save a diagnostic ZIP on your own machine. It works even when uploads are disabled, which helps on locked-down company laptops.

Opt-in Cloud connection

On macOS and Linux, the opt-in Cloud connection now lets you:

  • Send images to Cloud conversations.
  • Pick a model and reasoning effort for the Cloud task.
  • Archive or restore Cloud conversations.

Cloud tasks use your plan’s Codex limits. See my Codex usage limits guide before you move heavy work there.

Animated GIFs and audio

Turn on animated GIF generation and editing with one flag. Audio-capable models can also receive attached recordings, with no flag needed.

[features]
image_generation_animation = true

OSC 777 notifications

If your terminal supports OSC 777 desktop notifications, you can now pick them. Set it under the [tui] table:

[tui]
notification_method = "osc777"

multi_agent is now agents.enabled

features.multi_agent is deprecated. Codex warns you if it is set and points you to agents.enabled, which defaults to true. To switch subagent tools off:

[agents]
enabled = false

A Sample config.toml With Everything

Here is one file that turns on the new features and adds OpenRouter as an extra provider. Keep model_provider on openai if you want OpenAI as the default.

model_provider = "openai"

[features]
tui_workspace = true
image_generation_animation = true

[tui]
notification_method = "osc777"

[agents]
enabled = true

[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"

[model_providers.openrouter.auth]
command = "sh"
args = ["-c", "echo $OPENROUTER_API_KEY"]

[projects."/home/you/code/my-app"]
trust_level = "trusted"

One TOML rule to remember: top-level keys like model_provider must sit above the first [table] header. If you put them lower, TOML treats them as part of the table above.

My Take

Side-chat tabs are the headline, and they fix a real habit. Most of us open a second terminal just to ask a quick question, and now that lives in one window with saved history.

The --trust change is the one I would act on today. If your scripts depend on a project .codex/config.toml, they may quietly lose those settings until you trust the folder. Comparing tools? My Codex vs Claude Code post covers how the two compare.

Troubleshooting: Common Problems and Fixes

  • No side pane after enabling the flag: check that tui_workspace = true sits under [features], then fully restart Codex. Run codex --version to confirm you are on 0.168 or newer.
  • Only one side chat, no tabs: multiple tabs came in 0.169. Update with npm install -g @openai/codex@0.169.0.
  • Zoom shortcut does nothing: your leader key may be different. Open /keymap to see the current binding.
  • Project MCP servers stopped loading in exec: the folder is untrusted. Review it, then run once with --trust or add a trust_level entry.
  • “Unknown model” warning with OpenRouter: you are using env_key. Switch to the auth command block so Codex can fetch the model catalog.
  • Your custom Ollama block does not work: check that you did not try to redefine ollama, lmstudio or openai. Use a new ID like local_ollama.
  • Warning about multi_agent: delete multi_agent from [features] and use [agents] with enabled instead.
  • Images do not show in tmux: on Ghostty or Kitty, set tmux allow-passthrough to all.
  • Profile stopped working: [profiles] tables were removed in 0.134.0. Move the settings to a <name>.config.toml file.

Frequently Asked Questions

When were Codex CLI 0.168 and 0.169 released?

Both were released on November 13, 2026, according to the official Codex changelog.

Are side-chat tabs on by default?

No. The terminal workspace is opt-in. Add tui_workspace = true under [features] in config.toml and restart Codex.

Do side chats survive a restart?

Yes, saved local side chats can be reopened after you restart Codex, starting with version 0.169.

Can I use Codex CLI with OpenRouter or Ollama?

Yes. Add OpenRouter as a custom entry under [model_providers]. Ollama is built in, so set oss_provider = "ollama" and run codex --oss.

What does the trust flag do?

It saves project trust when you run codex exec or codex review. Without trust, project config and MCP servers stay disabled in that folder.

Where does the Ctrl+S diagnostic ZIP go?

It is saved on your own machine from the terminal report editor. It works even when feedback uploads are disabled.

Is features.multi_agent removed?

It is deprecated, not removed. Codex warns you when it is set and points you to agents.enabled, which is the setting to use now.

Sources

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Excited woman in a green hoodie in a dark studio holding a CODEX card, hook: Side chat tabs in Codex CLI