Tools Reference

Tools Reference

These are the tools Codex Free exposes to ChatGPT. 27 in default single-project mode, 29 in multi-project mode. Turning off artifactIngress.enabled removes import_host_file, dropping the count by one. When MCP bridging is configured, your other servers' tools are re-exposed here too, on top of these.

Every project-scoped path resolves relative to the active project root: --work-dir in single-project mode, or the root the current ChatGPT conversation selected in multi-project mode.

---

Structured primitives

Cheaper and safer than shelling out for the same job, and identical on Windows and POSIX.

Tool	Description
read_file	Read a file's contents, a bounded window at a time, with optional line offset/limit.
write_file	Write content to a file, creating parent directories if needed.
import_host_file	Stream one ChatGPT attachment or generated file into a new project-relative path, with bounded size, SHA-256 verification, and atomic no-overwrite publication. (Removed when artifactIngress.enabled is false.)
run_command	Execute a command in the work directory (allowlist-restricted by allowedCommands).
git_status	Show git status, parsed into changed files with status codes.
show_changes	Compare the working tree with the project-open or last-review checkpoint, optionally advancing the baseline; compatible hosts render an interactive review card. See Review Checkpoints.
git_push	Push commits to a remote.
git_commit	Create a commit, optionally staging all tracked changes.
git_log	Show recent commit history.
glob	Find files matching a glob pattern (.gitignore-aware).
grep	Search file contents by regex, with optional context lines (.gitignore-aware).
list_directory	List files and directories with name, type, and size.
tree	Print a directory tree as ASCII art.

Ported from Codex's own agent tools

Tool	Codex name	Description
apply_patch	apply_patch	Edit files with a context patch instead of rewriting them.
exec_command	exec_command	Run a shell command; returns output, or a session id if it is still running.
write_stdin	write_stdin	Write to (or poll) a running exec_command session.
view_image	view_image	Load a local image file for visual inspection.
update_plan	update_plan	Track a multi-step plan; saved to disk so a later conversation can pick it up.
clock_curr_time	clock.curr_time	Current time in UTC.
clock_sleep	clock.sleep	Pause for a given duration (capped at 5 minutes).
skills_list	skills.list	List the SKILL.md skills installed for this project and user.
skills_read	skills.read	Read a skill's instructions, or another file in its package.

Codex's dotted names are flattened to underscores because MCP tool names must match ^[a-zA-Z0-9_-]{1,64}$.

Always-on tools (no Codex counterpart)

Tool	Description
get_agent_brief	Return the whole operating brief — behaviour, environment, saved state, project rules — in one call.
get_environment	Report the OS, the shell exec_command uses, the work directory, and what the policy allows.
get_project_doc	Read the project's AGENTS.md instructions.
remember	Save one durable note about the task under a short key.
recall	Return the plan and notes saved by earlier turns or conversations.

Why these exist: Codex puts its brief in a system prompt, the OS/shell in an <environment_context> message, and AGENTS.md straight into the prompt — all channels an MCP server doesn't have, so the same facts become tool calls (and part of the server's instructions). remember/recall exist for the opposite reason: a chat window loses its context, so state is written to disk. See Context and Memory.

Multi-project mode adds two

Tool	Description
list_projects	Search the read-only project catalogue before binding. Returns relative selectors, names, aliases, descriptions, trust metadata, and sanitized warnings. It never selects a project.
set_project_root	Bind the current ChatGPT conversation to one existing directory beneath the access root. Re-selecting the same directory is idempotent; switching is rejected.

See Multi-Project Mode.

---

Two deliberate differences from Codex

• apply_patch takes a JSON string. In Codex it's a freeform tool whose entire body is the raw patch. MCP has no freeform tools, so the patch goes in an input string parameter. The patch format itself is unchanged.
• exec_command runs with plain pipes, not a PTY. Codex's own tty parameter documents pipes as the default, so ordinary commands behave the same; tty: true is rejected rather than silently ignored. Programs that only enable interactive behaviour when attached to a terminal act as if piped.

Long-running processes

exec_command returns a session_id when a process keeps running; write_stdin resumes, feeds, or polls it. For ChatGPT calls carrying conversation metadata, the process belongs to that hashed conversation identity, so write_stdin can reach it even after ChatGPT replaces the connector transport between calls. Generic MCP clients keep transport-session ownership.

Process handles are in memory only — they don't survive a Codex Free restart, and exec.idleTimeoutMs still reaps abandoned sessions. clock_sleep caps at 5 minutes (vs Codex's 12 hours) because a longer wait would outlive the HTTP request through the tunnel.

Which shell runs

Decided by name, not host platform (like Codex's Shell::derive_exec_args):

Shell	Invoked as
sh, bash, zsh, anything else	<shell> -c "<cmd>"
powershell, pwsh	<shell> -NoProfile -Command "<cmd>"
cmd	cmd /c "<cmd>"

The default comes from $SHELL on every platform — so starting the server from Git Bash on Windows gets bash (real ls -la, pipes, $VAR) rather than PowerShell. Override with exec.defaultShell or the per-call shell argument. The resolved shell is published three ways so a client only has to read one: the initialize instructions, exec_command's description, and get_environment.

Structured output

Every tool that advertises an outputSchema also returns matching structuredContent. exec_command/write_stdin return Codex's unified-exec object; show_changes returns its review summary; import_host_file returns destination + byte count + SHA-256 receipt; clock_curr_time returns { current_time }; get_environment returns the environment object; get_project_doc returns { files, content }; skills_list returns { skills, content }. The rest return { content: <text> }.

---

See also

• How It Works — the lifecycle of a tool call.
• Security Model — what each tool can and cannot reach.
• Bridging MCP Servers — adding tools from your other MCP servers.