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)

string

Usually the first user message in the thread, if available

boolean

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

string

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

number

Unix timestamp (seconds) when the thread was created

number

Unix timestamp (seconds) when the thread was last updated

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)

string | null

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

string

Working directory captured for the thread

Turn[]

Array of turns (only populated when explicitly requested)

Start a Thread

Create a new conversation thread with optional configuration.

Method

thread/start

Parameters

string

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

string

Model provider (e.g., openai)

string

Working directory for the thread

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

string

Sandbox mode

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

string

Agent personality

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

string

Optional metrics tag (service_name)

Response

Thread

The created thread object

string

Active model for the thread

string

Active model provider

string

Working directory

string

Active approval policy

SandboxPolicy

Active sandbox policy

Notifications

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"
  }
}

{
  "id": 10,
  "result": {
    "thread": {
      "id": "thr_123",
      "preview": "",
      "modelProvider": "openai",
      "createdAt": 1730910000,
      "status": { "type": "idle" }
    },
    "model": "gpt-5.1-codex",
    "modelProvider": "openai",
    "cwd": "/Users/me/project",
    "approvalPolicy": "never",
    "sandbox": {
      "type": "workspaceWrite",
      "writableRoots": ["/Users/me/project"],
      "networkAccess": true
    }
  }
}

{
  "method": "thread/started",
  "params": {
    "thread": {
      "id": "thr_123",
      "preview": "",
      "modelProvider": "openai",
      "createdAt": 1730910000
    }
  }
}

Resume a Thread

Reopen an existing thread by ID to continue the conversation.

Method

thread/resume

Parameters

string

required

Thread ID to resume

string

Override personality for resumed thread

Response

Same as thread/start response.

Example

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

{
  "id": 11,
  "result": {
    "thread": {
      "id": "thr_123",
      "preview": "Help me debug this issue",
      "modelProvider": "openai",
      "createdAt": 1730910000
    },
    "model": "gpt-5.1-codex",
    "modelProvider": "openai"
  }
}

Fork a Thread

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

Method

thread/fork

Parameters

string

required

Thread ID to fork from

Response

Thread

The newly created forked thread (with a new ID)

Notifications

notification

Emitted for the new forked thread

Example

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

{
  "id": 12,
  "result": {
    "thread": {
      "id": "thr_456",
      "preview": "Help me debug this issue",
      "modelProvider": "openai",
      "createdAt": 1730910100
    }
  }
}

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

List Threads

Page through stored rollouts with optional filtering and pagination.

Method

thread/list

Parameters

string

Opaque pagination cursor from previous response

number

Page size (server defaults if unset)

string

Sort key: created_at (default) or updated_at

string[]

Filter by model providers (empty/null includes all)

string[]

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

boolean

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

string

Filter by exact working directory path

string

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

Response

Thread[]

Array of thread objects

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"
  }
}

{
  "id": 20,
  "result": {
    "data": [
      {
        "id": "thr_a",
        "preview": "Create a TUI",
        "modelProvider": "openai",
        "createdAt": 1730831111,
        "updatedAt": 1730831111,
        "status": { "type": "notLoaded" }
      },
      {
        "id": "thr_b",
        "preview": "Fix tests",
        "modelProvider": "openai",
        "createdAt": 1730750000,
        "updatedAt": 1730750000,
        "status": { "type": "notLoaded" }
      }
    ],
    "nextCursor": "opaque-token-or-null"
  }
}

Read a Thread

Fetch a stored thread by ID without resuming it.

Method

thread/read

Parameters

string

required

Thread ID to read

boolean

default:false

When true, include turns and their items from rollout history

Response

Thread

Thread object with status and optional turns

Example

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

{
  "method": "thread/read",
  "id": 23,
  "params": {
    "threadId": "thr_123",
    "includeTurns": true
  }
}

{
  "id": 23,
  "result": {
    "thread": {
      "id": "thr_123",
      "status": { "type": "notLoaded" },
      "turns": [
        {
          "id": "turn_1",
          "items": [...],
          "status": "completed"
        }
      ]
    }
  }
}

Archive a Thread

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

Method

thread/archive

Parameters

string

required

Thread ID to archive

Response

object

Empty object on success

Notifications

notification

Emitted after successful archive

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

Example

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

{
  "id": 21,
  "result": {}
}

{
  "method": "thread/archived",
  "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

Emitted when a new thread starts or forks

Emitted when a loaded thread’s status changes

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

Emitted after archiving a thread

Emitted after unarchiving a thread

Emitted when a thread is unloaded (no more subscribers)

Emitted when a thread’s name changes

Emitted with token usage updates during turns

Next Steps

Turns

Send user input and start a turn

Items

Understand turn items and streaming

​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