Threads - Codex CLI

A Thread is a conversation between a user and the Codex agent. Each thread contains multiple turns and persists as a rollout file on disk.

Thread Object

string

Unique thread identifier (e.g., thr_123)

preview

string

Usually the first user message in the thread, if available

ephemeral

boolean

Whether the thread is ephemeral and should not be materialized on disk

modelProvider

string

Model provider used for this thread (e.g., openai)

createdAt

number

Unix timestamp (seconds) when the thread was created

updatedAt

number

Unix timestamp (seconds) when the thread was last updated

status

ThreadStatus

Current runtime status for the thread

Show Status types

notLoaded - Thread not currently loaded in memory
idle - Thread loaded but no active turn
systemError - Thread encountered a system error
active - Thread has an active turn (includes activeFlags array)

path

string | null

Path to the thread rollout file on disk (null for ephemeral threads)

cwd

string

Working directory captured for the thread

turns

Turn[]

Array of turns (only populated when explicitly requested)

Start a Thread

Create a new conversation thread with optional configuration.

Method

thread/start

Parameters

model

string

Model to use (e.g., gpt-5.1-codex)

modelProvider

string

Model provider (e.g., openai)

cwd

string

Working directory for the thread

approvalPolicy

string

Approval policy for commands and file changes

never - Never ask for approval
untrusted - Ask for approval on untrusted operations
on-request - Always ask for approval
on-failure - Ask for approval on failures
reject - Reject all approval requests

sandbox

string

Sandbox mode

read-only - Read-only file system access
workspace-write - Write access to workspace
danger-full-access - Full system access

personality

string

Agent personality

friendly - Friendly and conversational
pragmatic - Direct and efficient
none - No personality modifier

serviceName

string

Optional metrics tag (service_name)

Response

thread

Thread

The created thread object

model

string

Active model for the thread

modelProvider

string

Active model provider

cwd

string

Working directory

approvalPolicy

string

Active approval policy

sandbox

SandboxPolicy

Active sandbox policy

Notifications

thread/started

notification

Emitted when the thread starts

{
  "method": "thread/started",
  "params": {
    "thread": { "id": "thr_123", ... }
  }
}

Example

{
  "method": "thread/start",
  "id": 10,
  "params": {
    "model": "gpt-5.1-codex",
    "cwd": "/Users/me/project",
    "approvalPolicy": "never",
    "sandbox": "workspaceWrite",
    "personality": "friendly"
  }
}

Resume a Thread

Reopen an existing thread by ID to continue the conversation.

Method

thread/resume

Parameters

threadId

string

required

Thread ID to resume

personality

string

Override personality for resumed thread

Response

Same as thread/start response.

Example

{
  "method": "thread/resume",
  "id": 11,
  "params": {
    "threadId": "thr_123",
    "personality": "friendly"
  }
}

Fork a Thread

Branch from an existing thread into a new thread ID with copied history.

Method

thread/fork

Parameters

threadId

string

required

Thread ID to fork from

Response

thread

Thread

The newly created forked thread (with a new ID)

Notifications

thread/started

notification

Emitted for the new forked thread

Example

{
  "method": "thread/fork",
  "id": 12,
  "params": {
    "threadId": "thr_123"
  }
}

List Threads

Page through stored rollouts with optional filtering and pagination.

Method

thread/list

Parameters

cursor

string

Opaque pagination cursor from previous response

limit

number

Page size (server defaults if unset)

sortKey

string

Sort key: created_at (default) or updated_at

modelProviders

string[]

Filter by model providers (empty/null includes all)

sourceKinds

string[]

Filter by source kinds (cli, vscode, etc.)

archived

boolean

When true, list archived threads only. When false/null, list non-archived threads

cwd

string

Filter by exact working directory path

searchTerm

string

Filter by substring match in thread title (case-sensitive)

Response

data

Thread[]

Array of thread objects

nextCursor

string | null

Cursor for next page (null if no more pages)

Example

{
  "method": "thread/list",
  "id": 20,
  "params": {
    "cursor": null,
    "limit": 25,
    "sortKey": "created_at"
  }
}

Read a Thread

Fetch a stored thread by ID without resuming it.

Method

thread/read

Parameters

threadId

string

required

Thread ID to read

includeTurns

boolean

default:false

When true, include turns and their items from rollout history

Response

thread

Thread

Thread object with status and optional turns

Example

{
  "method": "thread/read",
  "id": 22,
  "params": {
    "threadId": "thr_123"
  }
}

Archive a Thread

Move a thread’s rollout file into the archived directory.

Method

thread/archive

Parameters

threadId

string

required

Thread ID to archive

Response

{}

object

Empty object on success

Notifications

thread/archived

notification

Emitted after successful archive

{
  "method": "thread/archived",
  "params": { "threadId": "thr_b" }
}

Example

{
  "method": "thread/archive",
  "id": 21,
  "params": {
    "threadId": "thr_b"
  }
}

Other Thread Operations

thread/unarchive

Move an archived thread back to sessions directoryReturns: Restored thread object

thread/name/set

Set or update a thread’s user-facing nameReturns: Empty object {}

thread/loaded/list

List thread IDs currently loaded in memoryReturns: { data: string[], nextCursor: string | null }

thread/unsubscribe

Unsubscribe from thread events (unloads if last subscriber)Returns: { status: "unsubscribed" | "notSubscribed" | "notLoaded" }

thread/rollback

Drop last N turns from thread historyReturns: Updated thread with turns populated

thread/compact/start

Trigger conversation history compactionReturns: Empty object {} (progress via notifications)

Thread Notifications

thread/started

Emitted when a new thread starts or forks

thread/status/changed

Emitted when a loaded thread’s status changes

{
  "method": "thread/status/changed",
  "params": {
    "threadId": "thr_123",
    "status": { "type": "active", "activeFlags": [] }
  }
}

thread/archived

Emitted after archiving a thread

thread/unarchived

Emitted after unarchiving a thread

thread/closed

Emitted when a thread is unloaded (no more subscribers)

thread/name/updated

Emitted when a thread’s name changes

thread/tokenUsage/updated

Emitted with token usage updates during turns

Next Steps

Turns

Send user input and start a turn

Items

Understand turn items and streaming

App Server API

TypeScript SDK

​Thread Object

​Start a Thread

​Method

​Parameters

​Response

​Notifications

​Example

​Resume a Thread

​Method

​Parameters

​Response

​Example

​Fork a Thread

​Method

​Parameters

​Response

​Notifications

​Example

​List Threads

​Method

​Parameters

​Response

​Example

​Read a Thread

​Method

​Parameters

​Response

​Example

​Archive a Thread

​Method

​Parameters

​Response

​Notifications

​Example

​Other Thread Operations

thread/unarchive

thread/name/set

thread/loaded/list

thread/unsubscribe

thread/rollback

thread/compact/start

​Thread Notifications

​Next Steps

Turns

Items

Thread Object

Start a Thread

Method

Parameters

Response

Notifications

Example

Resume a Thread

Method

Parameters

Response

Example

Fork a Thread

Method

Parameters

Response

Notifications

Example

List Threads

Method

Parameters

Response

Example

Read a Thread

Method

Parameters

Response

Example

Archive a Thread

Method

Parameters

Response

Notifications

Example

Other Thread Operations

Thread Notifications

Next Steps