> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Codex

> Use Dial from Codex by dropping the Dial skill into your Codex config.

Drop the Dial skill into your Codex config so the agent learns how to drive the `dial` CLI on demand. Once installed, Codex can send messages, place calls, and wait for events without you re-explaining the surface.

## Install

Pick one of two paths. **Option 1** drops the Dial CLI skill into Codex, so the agent drives the `dial` CLI on demand. **Option 2** wires Dial's [MCP server](/integrations/tools/mcp) into Codex natively, so the agent calls Dial's tools directly.

### Option 1 — CLI skill (Recommended)

First, get the `dial` CLI on your PATH:

```bash title="Shell install"
curl -fsSL https://getdial.ai/install | bash
```

```text title="Agent prompt"
Follow https://getdial.ai/skills.md to install and onboard the dial CLI.
```

Then drop the Codex-specific Dial skill into your config:

```bash
dial auth verify-otp --code <code> --agent codex
```

`auth verify-otp` verifies your code first, then copies the Dial skill into Codex's standard config directory. Re-run the command anytime (after a CLI upgrade, for example) to overwrite the skill in place — the verification step is a no-op once you're signed in.

A single markdown skill describing the `dial` CLI — its commands, flags, and conventions, mirroring the [CLI reference](/documentation/cli/commands) — gets copied in. Codex loads the skill when a Dial-related task comes up; nothing else is touched.

### Option 2 — MCP server

Register Dial's MCP server with Codex and the agent calls Dial's tools directly — no `dial` CLI shell-out. The local (stdio) server runs via `npx`, reuses your saved CLI key, and needs no global install.

```bash title="Codex CLI"
# Local stdio server (reuses your saved CLI key)
codex mcp add dial -- npx -y @getdial/cli mcp
```

```toml title="config.toml"
# ~/.codex/config.toml
[mcp_servers.dial]
command = "npx"
args = ["-y", "@getdial/cli", "mcp"]
```

`codex mcp add` only handles stdio servers; for the remote [Streamable HTTP](/integrations/tools/mcp) server (browser OAuth, no local CLI), add a `url` table to `~/.codex/config.toml` instead:

```toml title="config.toml"
# ~/.codex/config.toml
[mcp_servers.dial]
url = "https://getdial.ai/mcp"
```

See the [MCP page](/integrations/tools/mcp) for the full tool list and the remote OAuth flow, and Codex's own [MCP docs](https://developers.openai.com/codex/mcp) for server-management details.

## Use it

Both paths work the same way — just ask in plain language:

> Send an SMS to +14155550123 with the body "running late, ETA 10 min".

Codex figures out the rest. With the **MCP server** it calls Dial's tools directly; with the **CLI skill** it picks the right `dial` command and runs it. See [Using Dial from an agent](/documentation/get-started/using-dial-from-an-agent) for more examples.

## Inbound event handling (Suggestion)

You can also wake Codex automatically when a Dial event arrives by wiring a [CLI command target](/integrations/methods/cli-command-target): for each inbound event, the listen daemon spawns a handler that delivers a fresh prompt to Codex's non-interactive mode.

First install the listen daemon:

```bash
dial listen install
```

### 1. Write a handler

```bash
#!/usr/bin/env bash
# /usr/local/bin/handle-dial-event-codex
event="$1"

type=$(jq -r '.type'        <<<"$event")
from=$(jq -r '.from // ""'  <<<"$event")
body=$(jq -r '.body // ""'  <<<"$event")

prompt=$(cat <<EOF
A Dial event just arrived. Decide what to do and act on it.

  type: $type
  from: $from
  body: $body

raw event JSON:
$event
EOF
)

# Detach a fresh Codex run and return right away.
nohup codex exec "$prompt" </dev/null >>~/.dial/codex.log 2>&1 &
disown
exit 0
```

Swap `codex exec` for whatever your install uses to start a one-shot agent run (the Codex CLI's non-interactive subcommand depending on version).

### 2. Register

```bash
chmod +x /usr/local/bin/handle-dial-event-codex
dial local-target add cmd /usr/local/bin/handle-dial-event-codex
```

The `nohup … & disown` pattern keeps Codex running after the handler exits, so a multi-minute agent run never collides with the daemon's per-attempt `--timeout`. See [CLI command target](/integrations/methods/cli-command-target) for the full reference, delivery semantics, and the once-retry behavior.