Tools Reference

Tools Reference

These are the tools Codexify exposes to ChatGPT. 34 in default single-project mode, 36 in multi-project mode. Four counted helpers — check_for_updates, setup_status, doctor, and self_update_status — are app-only, leaving 30 and 32 model-visible tools respectively. Turning off artifactIngress.enabled removes import_host_file and artifactEgress.enabled removes export_host_file, each dropping both applicable counts by one. Configuring conversationAuthToken adds the model-visible setup gate tool (+1), producing 35/37 advertised and 31/33 model-visible tools. uiWidgets: false does not change the registry count; it removes Codexify's built-in MCP App resources/widget metadata while keeping the underlying tools and private helpers. 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.)
export_host_file	Export one project-relative file as a durable opaque MCP resource_link — no local path or base64 text. Codexify retains an immutable disk snapshot when eligible; otherwise the capability can resolve the latest safe source-path version when fallbackToSource is enabled. (Removed when artifactEgress.enabled is false.)
git_status	Show git status, parsed into changed files with status codes.
show_diff	Present the working-tree diff from the project-open or last-diff checkpoint and, by default, record the emitted snapshot as the next incremental baseline. The model-visible result is concise text; with uiWidgets: true, compatible hosts receive the bounded complete diff payload in component-only result _meta for an interactive diff card, not model context. With uiWidgets: false, patch generation/widget metadata are skipped but checkpoint behavior remains. See Diff 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}$.

Codexify-native tools (no Codex counterpart)

Tool	Description
setup	Authorize the current ChatGPT conversation or transport by submitting the configured 64-lowercase-hex ref; advertised only when conversationAuthToken is configured. Its optional connectorVersion echoes the version marker from the cached tool description so the setup app can classify the conversation schema. The reference is not retained.
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.
check_for_updates	Force a fresh bounded latest-release check for the setup app. This private app-only tool bypasses the normal latest-version cache and is intentionally hidden from the model.
setup_status	Return current server/update state, connector-schema state, configured worktree mode, and current workspace state to the setup app. The private app-only tool accepts an optional bounded conversationVersion and forceUpdateCheck; polling it never records a connector reload.
doctor	Run the same read-only diagnostic engine as codexify doctor against the active configuration, returning deterministic text plus structured checks to the setup app. Private and app-only.
self_update	After an explicit user request, download and verify the latest Codexify release and schedule a detached executable replacement; service-supervised updates stop/restart the service after the tool response is delivered. Requires confirm=true. After Codexify restarts, refresh the Codexify connector from ChatGPT Settings so its tool schema is reloaded. With uiWidgets: false, no updater component/component-only changelog payload is emitted; use codexify service logs -f for progress.
self_update_status	Read one durable update record by its opaque update ID and report update phase plus the responding process version. Private and app-only.
remember	Create one durable note under a new short key; it refuses to overwrite an existing key.
update_memory_note	Replace one existing durable note without creating a missing key.
forget_memory_note	Delete one existing durable note.
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 through exactly one of three mutually exclusive forms: path for a project, withoutProject: true for private scratch, or resumePath for an exact workspace recorded by another ChatGPT conversation. A path call may add createWorktree: true/false to override configured placement for that selection only. Repository URLs reuse or clone as documented; resumePath instead reuses an existing validated direct checkout, managed worktree, or persistent scratch root unchanged and never clones or creates a worktree. Bindings are immutable; an exact repeated choice is idempotent, while conflicting placement or workspace choices fail. Resume requires stable ChatGPT conversation metadata; transport-only sessions cannot use it.

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 Codexify restart, and exec.idleTimeoutMs still reaps abandoned sessions. They also belong to the original conversation identity: resuming the same filesystem workspace through resumePath in a new conversation does not transfer resident process handles. 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; import_host_file returns destination + byte count + SHA-256 receipt; export_host_file returns exact fields path, name, bytes, sha256, mimeType, snapshotStored, and fallbackToSource, alongside a standard MCP resource_link; clock_curr_time returns { current_time }; get_environment returns the environment object; get_project_doc returns { files, content }; skills_list returns { skills, content }. The app-only status tools and self_update return their own structured update/diagnostic/setup objects. Other fixed text tools use { content: <text> }. show_diff is the deliberate exception: it advertises no output schema; with uiWidgets: true its diff payload lives in component-only result _meta rather than model-visible structuredContent, while uiWidgets: false omits that payload entirely.

For MCP protocol version 2026-07-28 and newer, cacheable tool, prompt, resource, resource-template, and resource-read responses receive private, immediately stale defaults (ttlMs: 0) when those hints are absent. Older clients retain their legacy wire shapes. Bridged resource reads preserve upstream cache hints when provided and remain capability-bounded.

---

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.