AI

Guide and fork Codex conversations

Steer running work, queue follow-ups, send to existing threads from the CLI, choose a working directory, and fork context.

Start with Open Codex chat if you have not used the agent before.

Guide a running turn or queue a follow-up

While Codex is working, the composer offers Steer and Queue.

Use Steer to send guidance to the running turn. For example, if Codex is editing a notebook and you notice the wrong dataset, write "Use the August data in data/august.csv" and click Steer. CoCalc requests steering of the active turn. If the turn ends at that boundary, the request can become queued instead; check its displayed status to see how it was accepted.

Use Queue for a separate follow-up that should run after the current turn, such as "After this finishes, summarize the changed cells." Type the message and click Queue. It appears with a queued label while it waits.

Steering supplies an instruction; it does not undo changes already made. Inspect the response and project state to confirm how Codex applied the guidance. When no Codex turn is running, the composer uses Send for a normal message instead.

Manage a queued or unsent message

A queued Codex message has controls alongside its status.

  1. Choose Edit to revise the request, then save the edit before the next turn starts. The saved version will be used for that turn; the UI can show edited version sent to identify it.
  2. Choose Steer if the waiting text should instead guide the currently running turn.
  3. Choose Cancel to cancel that queued request.

Check the message status after acting. Once execution has started, changing the displayed message is not the same operation as updating a waiting request.

A not sent message can be a cancelled request or a failed submission. When Submit again is offered, inspect the text before using it. If an error is reported, resolve it first, such as reconnecting an expired ChatGPT sign-in or updating the selected API key. Read the reported error instead of assuming that every failed request is an allowance problem. Retrying is an explicit submission, so verify the message text before sending it again.

Send to an existing thread from the CLI

Use an authenticated account with project access and working Codex credentials. Run these commands in the terminal where you installed the CoCalc CLI, using the profile for the intended site. Check cocalc project chat send --help first; older CLI releases may not include this command.

Identify the project, the chat document's path inside it, and the CoCalc thread ID. Use Thread ID in Codex settings, not the adjacent Session ID, or select it from the list below. Replace the example profile and chat path with your existing site's profile and chat document:

export CLI_PROFILE=cocalc-ai
export PROJECT_ID='REPLACE_WITH_FULL_PROJECT_ID'
export CHAT_PATH='/home/user/research.chat'

cocalc --profile "$CLI_PROFILE" --json project chat thread list \
  --project "$PROJECT_ID" --path "$CHAT_PATH"

The JSON data array contains thread_id, name, agent_kind, and archived. Select an existing, unarchived Codex/ACP thread. A thread ID alone does not identify the project or chat document; provide all three values. Inspect its model, access mode, and working directory before submitting work.

export THREAD_ID='REPLACE_WITH_LISTED_THREAD_ID'

cocalc --profile "$CLI_PROFILE" --json project chat thread status \
  --project "$PROJECT_ID" --path "$CHAT_PATH" --thread-id "$THREAD_ID"

cocalc --profile "$CLI_PROFILE" --json project chat send \
  --project "$PROJECT_ID" --path "$CHAT_PATH" --thread-id "$THREAD_ID" \
  'Inspect this project without changing files and summarize the next step.'

The send command saves a real user message and starts a turn when idle, or queues it behind active work. Add --guidance only when the message should guide a running turn; if that is no longer possible it can queue or start a normal turn. For multiline text, use --stdin < request.txt with a local UTF-8 file instead of message arguments. Empty messages and combining --stdin with message arguments are rejected.

A successful response returns data.state:"accepted" and a data.message_id; it acknowledges submission, not task completion. Inspect the thread for results and any requests requiring attention. If the CLI says the message was saved but submission was not confirmed, inspect that message before resending: an automatic retry could submit the work twice. The saved message remains in the chat document, and the command does not roll back any work already performed.

Set the working directory and keep session context

Open a thread's Codex settings and find Working directory under Model and session. Enter the directory where Codex should run subsequent turns and click Save.

CoCalc initially fills the working directory from the associated workspace root when available. A generated CoCalc chat otherwise uses the project home; an ordinary chat uses the directory containing its chat file. This matters when a project contains several repositories or related analyses. If you explicitly clear the directory setting, submission instead falls back to the chat file's containing directory. Set the directory explicitly when its choice matters to the task.

A workspace can use its generated chat or an existing chat selected with Use current chat tab in the workspace editor. Its Agent button opens the latest agent thread associated with that workspace chat. If there is no agent thread yet, open Chat and start a Codex turn there first.

Session ID is an advanced continuity setting. Keep the existing value when you only want to change directory. Clearing this field is not a reliable conversation reset: CoCalc can recover the live session ID from the thread. Start a new Codex chat when you need fresh conversation context. Workspace selection does not change project permissions.

Fork a chat to explore another approach

Use a fork when you want a new conversation that starts from an existing Codex session's context.

  1. Open the source chat's thread menu and choose Fork chat….
  2. Enter the New chat name and click Fork.
  3. Continue in the new chat with the alternative task or approach.

CoCalc creates a new chat linked to the original. For a Codex chat with an existing session, it forks the agent session and carries its context and configuration into the new one. The visible new chat starts empty: earlier messages are not copied into it. A link points back to the source discussion. Without an existing Codex session ID, configuration and linkage can be copied, but there is no model-session context to fork.

The fork is a conversation/session fork within the same project. It does not create a separate copy of project files or a Git worktree. Changes made from either chat therefore concern the shared project environment. Use separate directories or an explicitly prepared repository checkout when your experiment requires separate file state, and verify the new thread's working directory before asking it to edit files.