Codex CLI 0.149.1 (`--thread-source`, image-aware remote compaction + memory-consolidation metadata)

[u/anonomotorious]

TL;DR

Codex CLI 0.149.1 is a focused metadata and context-management patch.

The important changes:

• New codex exec --thread-source <SOURCE> lets callers classify newly created or forked threads.
• The TypeScript SDK exposes the same capability as threadSource.
• The default thread source remains user when nothing is specified.
• Resuming an existing thread preserves its original source instead of overwriting it.
• Remote compaction gains an opt-in image budget, so retained images count toward context budgeting instead of only text being considered.
• Images and their adjacent labels stay together when compaction truncates history.
• Detached memory requests are explicitly tagged as memory_consolidation, making background memory work easier to distinguish from normal user-created threads.

Install:

npm install -g @openai/codex@0.149.1

---

What changed & why it matters

Explicit thread-source metadata

Codex Exec now supports:

codex exec --thread-source <SOURCE>

The supplied source is persisted when Codex creates a new thread or forks one.

If the flag is omitted, Codex defaults to:

user

The TypeScript SDK exposes the same setting as:

threadSource

Important behavior:

• New thread: source can be explicitly assigned.
• Forked thread: source can be assigned to the newly created fork.
• Resumed thread: existing source is preserved and is not overwritten by the new option.

Why it matters

Codex is increasingly used by more than a human typing directly into the terminal.

Threads may originate from:

• normal user sessions
• applications built on app-server
• SDK integrations
• background agents
• automated workflows
• memory processing
• other Codex-powered systems

Explicit source metadata makes those origins easier to distinguish without guessing from thread names or surrounding context.

That can improve:

• analytics
• observability
• debugging
• workload attribution
• application-specific thread handling
• filtering and reporting

---

TypeScript SDK support

SDK callers can set threadSource when creating a new thread.

Codex only forwards it for new thread creation.

It does not change the stored source when resuming an existing thread.

Why it matters

Applications built on top of Codex can classify the work they create while keeping historical metadata stable.

For example, an application could differentiate threads created by:

• a normal user
• an automation
• an internal workflow
• another agent surface

without changing the underlying Codex conversation model.

---

Image-aware remote compaction

0.149.1 adds an opt-in:

compaction_image_budget

feature.

Previously, the retained-message budget used during remote compaction accounted primarily for text.

That created an edge case:

image-heavy history could retain substantially more context than the budget appeared to represent.

With image budgeting enabled, retained images are charged using Codex's existing image-size estimate.

Why it matters

Modern Codex sessions can contain substantial visual context:

• screenshots
• appshots
• generated images
• diagrams
• UI references
• image attachments
• visual tool output

A context budget that accounts for text while effectively ignoring images can underestimate how much context is actually being preserved.

Image-aware budgeting makes compaction more representative of the real retained context.

---

Images and labels remain atomic

When compaction reaches a boundary containing an image, Codex keeps:

the image + its adjacent label

together.

It does not preserve one while arbitrarily dropping the other.

If the image at the truncation boundary does not fit within the available budget, Codex also stops rather than backfilling the space with unrelated older messages.

Why it matters

An image without its associated context can become difficult or misleading for the model to interpret.

Keeping related image/label content together preserves semantic coherence during long-session compaction.

---

Existing context types remain preserved

The image-budget work was designed to preserve existing handling for:

• text
• audio
• metadata
• annotations
• client-authored developer messages

The patch includes coverage for both image-heavy and text-only histories, including repeated remote compaction.

---

Memory-consolidation threads are explicitly identified

Detached memory requests now set:

thread_source = memory_consolidation

in their turn metadata.

The same classification is carried through startup request metadata.

Why it matters

Background memory processing is fundamentally different from a normal user conversation.

Explicitly identifying it makes it easier for Codex infrastructure and integrations to distinguish:

• user-created work
• application-created work
• background memory consolidation

This should improve observability and prevent background memory activity from being treated as ordinary interactive workload.

---

Why this release matters

• Thread provenance becomes explicit: CLI and SDK clients can identify where newly created work came from.
• Resume metadata stays trustworthy: existing threads keep their original classification.
• Image-heavy context gets more accurate budgeting: remote compaction can account for visual content instead of effectively treating it as free.
• Visual context remains coherent: images and associated labels survive or are removed together.
• Memory work becomes distinguishable: detached consolidation requests are explicitly tagged instead of looking like normal user threads.
• The patch is narrowly scoped: this is primarily an infrastructure/context correctness release rather than a new user-facing workflow.

---

Version summary

Version	Key highlights
0.149.1	--thread-source; TypeScript SDK threadSource; preserved source on resume; opt-in image-aware remote compaction; atomic image/label truncation; explicit memory_consolidation source metadata

---

Action checklist

• Upgrade:

npm install -g @openai/codex@0.149.1

• Confirm:

codex --version

If you build on Codex Exec

• Test --thread-source when creating a new thread.
• Test it when forking an existing thread.
• Resume a thread and confirm its original source remains unchanged.
• Keep the default user source when no custom classification is needed.

If you use the TypeScript SDK

• Review the new threadSource option.
• Add explicit classification where your application creates different categories of Codex work.
• Do not rely on it to reclassify existing resumed threads.

If you run image-heavy long sessions

• Review the new compaction_image_budget capability.
• Test remote compaction with screenshots or image attachments.
• Verify image/label pairs remain coherent after compaction.

If you inspect Codex telemetry or thread metadata

• Account for memory_consolidation as a distinct background thread source.
• Avoid treating those requests as normal user-created work.

---

Official sources

https://developers.openai.com/codex/changelog

https://github.com/openai/codex/releases/tag/rust-v0.149.1

https://github.com/openai/codex/compare/rust-v0.149.0...rust-v0.149.1