Thread dropdown showing multiple threads with New Thread option
Threads are Codex conversations within a workspace. Each thread maintains its own conversation history, allowing you to work on different aspects of a task or try alternative approaches. Threads run through the selected registered host. The control plane stores and routes product state, while jaidu-agent owns the thread history, filesystem, Git, terminal, and Codex execution for the workspace.

​
What is a Thread?

A thread is a single conversation with Codex. Think of it like a chat thread:
  • Each thread has its own conversation history - messages, code changes, and context
  • Threads share the same files - changes from one thread are visible to all threads
  • Threads are independent processes - one can be running while another is idle
Key point: Threads share files but not conversation context. If Thread 1 makes changes, Thread 2 can see those file changes but doesn’t know what instructions Thread 1 received.

​
Understanding Token Limits

AI models have a context window - a limit on how much text they can “remember” in a conversation. When you hit this limit:
  • Codex may lose earlier parts of the conversation
  • Responses may become less accurate
  • You’ll see the context gauge turn orange or red
Solution: Start a new thread. The new thread gets a fresh context window while still having access to all your files.
Watch the context gauge in the chat interface. When it shows high usage (orange/red), consider starting a new thread.

​
When to Create a New Thread

Token limits reached

Context gauge shows high usage - start fresh to give Codex full context capacity.

Parallel work

Have Codex threads work on independent parts simultaneously (backend API + frontend UI).

Different approaches

Try an alternative solution without losing your original conversation.

Different configurations

Use one Codex variant for safer execution and another for faster iteration.

​
When NOT to Create a New Thread

  • Continuing related work - Keep using the same thread if Codex needs context from earlier messages
  • Providing feedback - Use the same thread to tell Codex what to fix
  • Small follow-ups - “Also add a loading spinner” belongs in the current thread
New threads don’t inherit conversation history. The new Codex thread won’t know what happened in previous threads unless you explain it again or it reads the file changes.
All threads within a workspace share the same repositories and git state. Changes made by one thread are visible to others.
Starting a new thread in an existing workspace does not create a new folder, worktree, or branch. Use branch/fork if you need a separate workspace lineage.

​
Creating a New Thread

1

Open the Thread Dropdown

Click the thread dropdown (showing “Latest” or the thread name) in the chat toolbar.
2

Click New Thread

Select + New Thread from the dropdown menu.
Thread dropdown showing New Thread option and list of existing threads
3

Start Your Conversation

The new thread opens with a fresh conversation. Describe what you want Codex to work on.
Give context about what’s already been done in other threads if relevant. Codex doesn’t have access to conversations from other threads.

​
Switching Between Threads

To switch to a different thread:
  1. Click the thread dropdown in the chat toolbar
  2. Select the thread you want to switch to
The dropdown shows:
  • Thread name - Based on the initial task or auto-generated
  • Latest indicator - Shows which thread was most recently active
Switching threads doesn’t interrupt any running Codex process. Each thread continues working independently.

​
Thread States

Threads can be in different states:
StateDescription
RunningCodex is actively processing and making changes
IdleWaiting for your input
Needs AttentionCodex is waiting for approval or has a question
The workspace sidebar shows the overall workspace state based on its threads.

​
Managing Threads

​
Renaming Threads

Threads are automatically named from the initial task description. Open the selected thread’s ... menu and choose Rename thread to change the name.

​
Viewing Thread History

Each thread maintains its complete conversation history. Scroll up in the conversation panel to view earlier messages and Codex actions.

​
Stopping Codex

If Codex is running in the current thread:
  1. Click the Stop button in the navbar, or
  2. Use the keyboard shortcut to stop execution
Stopping Codex may leave changes in an incomplete state. Review the changes panel to see what was modified.

​
Codex Configurations in Threads

Different threads can use different Codex configurations:
  1. Create a new thread
  2. Select a different Codex configuration before sending your message
  3. Each thread remembers which Codex configuration it is using
Use specialised Codex configurations for different tasks, for example a higher-reasoning variant for architecture work and a faster one for focused edits.

​
Thread Best Practices

​
When to Create New Threads

  • Task complexity - Break complex tasks into smaller threads
  • Token limits - Start fresh when conversations get long
  • Different approaches - Try alternative solutions without losing progress
  • Parallel work - Have Codex threads work on independent parts simultaneously

​
Keeping Threads Organised

  • One focus per thread - Keep each thread focused on a specific goal
  • Use workspace notes - Document which thread is for what purpose
  • Review before switching - Check the changes panel before switching threads

​
Resolving Conflicts Between Threads

When multiple threads make changes to the same files:
  1. The changes panel shows all modifications across threads
  2. Review changes carefully before committing
  3. Use the inline comment feature to mark areas needing attention
Git handles most conflicts automatically. For complex conflicts, see Git Operations.