codex-mcp

Overview Schema Source Related Servers Score Discussions Admin

Continue a Codex session

codex_continue

Resume an existing Codex session by providing a follow-up instruction, such as review feedback to fix, while preserving the original context for continued implementation.

Instructions

Resume an existing Codex session by sessionId with a follow-up prompt — typically review feedback that Codex should address. Preserves Codex context.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`cwd`	Yes	Absolute path of the workspace Codex should work in
`model`	No	Codex model override
`prompt`	Yes	Follow-up instruction, e.g. review findings to fix
`sandbox`	No	Codex sandbox policy (default: workspace-write)	workspace-write
`terminal`	No	Open a Terminal window streaming live progress (default: env CODEX_MCP_TERMINAL=1)
`sessionId`	Yes	Session/thread id returned by a previous codex_execute call
`timeoutMs`	No	Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes)
`writeNotes`	No	Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false).
`verifyCommand`	No	Acceptance command the server runs in cwd AFTER the Codex run settles (e.g. the test suite). Its exit code and output tail are returned in `verification` — deterministic evidence, not Codex's claim.
`reasoningEffort`	No	Reasoning effort override for the selected model
`verifyTimeoutMs`	No	Max time for verifyCommand in ms (default 10 minutes, cap 30).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`diff`	Yes
`runId`	Yes
`usage`	Yes
`errors`	Yes
`status`	Yes
`stderr`	Yes
`aborted`	Yes
`liveLog`	Yes
`accepted`	Yes
`attempts`	No
`commands`	Yes
`exitCode`	Yes
`timedOut`	Yes
`warnings`	Yes
`notesPath`	Yes
`sessionId`	Yes
`turnCount`	Yes
`redactions`	No
`attribution`	Yes
`fileChanges`	Yes
`parseErrors`	Yes
`agentMessage`	Yes
`verification`	No
`resumeReasons`	No
`sawCompletion`	Yes
`schemaVersion`	Yes
`unknownEvents`	Yes
`reviewFindings`	No
`outputTruncated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedv0.25.0Sep 9, 2026

addedInput schema / properties / verifyCommand

Added value: +{
+  "description": "Acceptance command the server runs in cwd AFTER the Codex run settles (e.g. the test suite). Its exit code and output tail are returned in `verification` — deterministic evidence, not Codex's claim.",
+  "type": "string"
+}

addedInput schema / properties / verifyTimeoutMs

Added value: +{
+  "description": "Max time for verifyCommand in ms (default 10 minutes, cap 30).",
+  "exclusiveMinimum": 0,
+  "maximum": 1800000,
+  "type": "integer"
+}

addedOutput schema / properties / accepted
```
Added value: +{
+  "type": "boolean"
+}
```

removedOutput schema / properties / agentMessage / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / agentMessage / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / commands / items / properties / exitCode / anyOf

Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / commands / items / properties / exitCode / type
```
Added value: +[
+  "number",
+  "null"
+]
```

removedOutput schema / properties / exitCode / anyOf

Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / exitCode / type
```
Added value: +[
+  "number",
+  "null"
+]
```

removedOutput schema / properties / liveLog / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / liveLog / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / notesPath / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / notesPath / type
```
Added value: +[
+  "string",
+  "null"
+]
```
addedOutput schema / properties / redactions
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / reviewFindings

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "dropped": {
+      "type": "number"
+    },
+    "droppedReasons": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "findings": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "expected": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "file": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "inScope": {
+            "type": "boolean"
+          },
+          "line": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "observed": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "severity": {
+            "enum": [
+              "CRITICAL",
+              "HIGH",
+              "MEDIUM",
+              "LOW"
+            ],
+            "type": "string"
+          },
+          "summary": {
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "severity",
+          "file",
+          "line",
+          "summary",
+          "expected",
+          "observed"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "improvements": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "file": {
+            "type": "string"
+          },
+          "id": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "summary": {
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "summary"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "outOfScopeCount": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "parseError": {
+      "type": "string"
+    },
+    "parsed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "parsed",
+    "findings",
+    "improvements",
+    "dropped",
+    "droppedReasons"
+  ],
+  "type": "object"
+}

removedOutput schema / properties / sessionId / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / sessionId / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedOutput schema / properties / verification

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "type": "string"
+        },
+        "durationMs": {
+          "type": "number"
+        },
+        "exitCode": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "outputTail": {
+          "type": "string"
+        },
+        "passed": {
+          "type": "boolean"
+        },
+        "redactions": {
+          "type": "number"
+        },
+        "skipped": {
+          "enum": [
+            "aborted",
+            "run-failed"
+          ],
+          "type": "string"
+        },
+        "timedOut": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "command",
+        "exitCode",
+        "timedOut",
+        "durationMs",
+        "outputTail",
+        "passed"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "sessionId",
-  "agentMessage",
-  "fileChanges",
-  "commands",
-  "usage",
-  "errors",
-  "parseErrors",
-  "unknownEvents",
-  "sawCompletion",
-  "warnings",
-  "turnCount",
-  "schemaVersion",
-  "status",
-  "runId",
-  "diff",
-  "attribution",
-  "exitCode",
-  "timedOut",
-  "aborted",
-  "outputTruncated",
-  "stderr",
-  "liveLog",
-  "notesPath"
-]New value: +[
+  "sessionId",
+  "agentMessage",
+  "fileChanges",
+  "commands",
+  "usage",
+  "errors",
+  "parseErrors",
+  "unknownEvents",
+  "sawCompletion",
+  "warnings",
+  "turnCount",
+  "schemaVersion",
+  "status",
+  "accepted",
+  "runId",
+  "diff",
+  "attribution",
+  "exitCode",
+  "timedOut",
+  "aborted",
+  "outputTruncated",
+  "stderr",
+  "liveLog",
+  "notesPath"
+]

Changed3 schema fields changedv0.13.0Jul 25, 2026

addedInput schema / properties / reasoningEffort

Added value: +{
+  "description": "Reasoning effort override for the selected model",
+  "enum": [
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh"
+  ],
+  "type": "string"
+}

changedInput schema / properties / timeoutMs / description

Previous value: -"Max execution time in ms (default: 30 minutes)"New value: +"Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes)"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "aborted": {
+      "type": "boolean"
+    },
+    "agentMessage": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "attempts": {
+      "type": "number"
+    },
+    "attribution": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "files": {
+              "items": {
+                "additionalProperties": {},
+                "properties": {},
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "untracked": {
+              "items": {
+                "additionalProperties": {},
+                "properties": {},
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "files",
+            "untracked"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "commands": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "command": {
+            "type": "string"
+          },
+          "exitCode": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "command",
+          "exitCode"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "diff": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "patch": {
+              "type": "string"
+            },
+            "status": {
+              "type": "string"
+            },
+            "statusTruncated": {
+              "type": "boolean"
+            },
+            "truncated": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "status",
+            "statusTruncated",
+            "patch",
+            "truncated"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "errors": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "exitCode": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "fileChanges": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "path",
+          "kind"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "liveLog": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "notesPath": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "outputTruncated": {
+      "type": "boolean"
+    },
+    "parseErrors": {
+      "type": "number"
+    },
+    "resumeReasons": {
+      "items": {
+        "enum": [
+          "timeout",
+          "transient-turn-failure",
+          "no-completion-marker"
+        ],
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "runId": {
+      "type": "string"
+    },
+    "sawCompletion": {
+      "type": "boolean"
+    },
+    "schemaVersion": {
+      "type": "number"
+    },
+    "sessionId": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "status": {
+      "enum": [
+        "success",
+        "partial",
+        "failed",
+        "aborted"
+      ],
+      "type": "string"
+    },
+    "stderr": {
+      "type": "string"
+    },
+    "timedOut": {
+      "type": "boolean"
+    },
+    "turnCount": {
+      "type": "number"
+    },
+    "unknownEvents": {
+      "type": "number"
+    },
+    "usage": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "cachedInputTokens": {
+              "type": "number"
+            },
+            "inputTokens": {
+              "type": "number"
+            },
+            "outputTokens": {
+              "type": "number"
+            },
+            "reasoningOutputTokens": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "inputTokens",
+            "cachedInputTokens",
+            "outputTokens",
+            "reasoningOutputTokens"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "warnings": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "sessionId",
+    "agentMessage",
+    "fileChanges",
+    "commands",
+    "usage",
+    "errors",
+    "parseErrors",
+    "unknownEvents",
+    "sawCompletion",
+    "warnings",
+    "turnCount",
+    "schemaVersion",
+    "status",
+    "runId",
+    "diff",
+    "attribution",
+    "exitCode",
+    "timedOut",
+    "aborted",
+    "outputTruncated",
+    "stderr",
+    "liveLog",
+    "notesPath"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.8.0Jul 16, 2026

addedInput schema / properties / writeNotes

Added value: +{
+  "description": "Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false).",
+  "type": "boolean"
+}

First observedv0.2.0Jul 10, 2026

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden of behavioral disclosure. It only states that the session is resumed and context preserved; it does not mention that Codex may execute in a mutable workspace, run verification commands, open a terminal, or persist notes. These are significant side effects for a code-execution tool and are not surfaced in the prose description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler: the action, target, and context-preserving benefit are all front-loaded. The description earns each word and is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex (11 parameters, code execution), but the schema describes every parameter and an output schema exists, so the description is not required to restate details. It supplies the missing high-level purpose and typical usage. It stops short of full completeness because it omits safety/behavioral context that an annotation-lacking execution tool would benefit from, though the schema partially compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with meaningful descriptions for all 11 parameters, so the baseline is 3. The description adds only that the prompt is typically review feedback, which largely restates the schema's example for prompt. No additional parameter-level meaning is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Resume an existing Codex session by sessionId with a follow-up prompt'. It also adds the key differentiator 'Preserves Codex context', which separates it from starting a new session. It does not explicitly name sibling tools, but the purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a concrete use case: 'typically review feedback that Codex should address', so an agent knows when continuing is appropriate. It does not explicitly contrast with codex_execute or codex_review, nor state when not to use this tool, so it falls short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server