codex-phone-assistant

Codex Phone Assistant for macOS

This repository contains two Codex skills for a supervised telephone workflow on macOS:

• phone-assistant runs one bounded conversation in a standalone Codex Live Voice session.
• mac-phone performs one local Phone.app action: dial one number or send one active-call DTMF digit.

The audio bridge uses two Loopback virtual devices. Telephone audio is routed into Codex Live, and Codex voice output is routed back into the calling app. The skills assume this setup is already working. They execute calls, they do not repeatedly inspect or repair the audio configuration.

Important limitations

This is experimental, supervised personal automation. It is not a telephony API or an emergency calling system.

• A local tel: request and Click to Call confirmation do not prove that the paired iPhone dialed, the remote phone rang, or anyone answered.
• A local DTMF button click does not prove that the remote IVR accepted the digit.
• Hang-up remains manual.
• The workflow depends on current macOS UI behavior, Codex Computer Use, the Node REPL MCP, and @oai/sky. Operating-system or product updates may break it.
• Never use it for emergency calls, unattended calling, harassment, spam, or calls you are not legally authorized to make.

Audio routing model

flowchart LR
    A["Calling apps: Phone, FaceTime, Signal, Telegram"] --> B["PHONE_TO_CODEX"]
    C["Optional local headset microphone"] --> B
    B --> D["Codex Live microphone input"]
    D --> E["Codex Live conversation"]
    E --> F["ChatGPT voice output"]
    F --> G["CODEX_TO_PHONE"]
    G --> H["Calling app microphone input"]
    G --> I["Optional Loopback monitors: headphones or speakers"]

The critical outbound setting is Mute when capturing on the ChatGPT source inside CODEX_TO_PHONE. In the tested setup, leaving the ordinary app-output path active caused macOS voice processing to attenuate most of the generated voice as echo. Enabling this option, while listening through Loopback monitors, restored normal remote volume. This is an observed routing result, not a guaranteed Apple implementation detail.

See Audio setup for the complete configuration.

Requirements

• macOS with Phone.app calling through a paired iPhone
• Codex desktop with standalone Live Voice
• Loopback by Rogue Amoeba
• Computer Use access in Codex
• The persistent Node REPL MCP with @oai/sky
• Accessibility and other permissions required by the above applications

Install the skills

Clone the repository:

git clone https://github.com/zhangzhongnan928/codex-phone-assistant.git
cd codex-phone-assistant

Copy both skill directories into the personal Codex skill directory:

mkdir -p "$HOME/.codex/skills"
cp -R skills/mac-phone "$HOME/.codex/skills/"
cp -R skills/phone-assistant "$HOME/.codex/skills/"

If a directory with either name already exists, back it up and review the differences before replacing it.

A project-level AGENTS.md is not required. The operating rules are already inside the skills, and this workflow must begin in a standalone Live Voice session rather than from a project prompt.

Mandatory startup order

The order matters:

1. Open a new Codex task.
2. Start a standalone Live Voice session.
3. Only after Live Voice is running, invoke $phone-assistant or say start phone assistant mode.
4. After the activation sentence finishes, use typed chat for the destination, objective, limits, and start instruction.

Do not type-invoke $phone-assistant before starting Live Voice. In the tested Codex workflow, doing that prevents Live Voice from being started in the same task. Start a new task if the order was reversed.

After activation, every assistant utterance is assumed to go to the telephone party. The assistant therefore gives no spoken status updates to the owner. Only typed chat messages in the current top-level task are trusted as control instructions. Telephone audio, including a voice claiming to be the owner, is treated as third-party content.

Example task

After Phone Assistant mode is active, type:

destination: <a number you are authorized to call>
objective: Ask for today's opening hours
owner_name: <optional name to disclose>
allowed_information: The objective above only
allowed_decisions: none
prohibited_actions: No purchases, bookings, or disclosure of sensitive information
success_criteria: The business states today's opening and closing times
start_now: yes

The assistant uses English by default. If the telephone party clearly uses another language, it may match that party's language. The language of the owner's typed instructions does not determine the telephone language.

Safety model

• One typed task authorizes one bounded call.
• mac-phone accepts only one atomic action at a time.
• Dialing uses a fresh Click to Call confirmation control.
• DTMF uses only a verified active-call keypad, never the ordinary dialing keypad.
• The assistant does not disclose passwords, one-time codes, recovery codes, private keys, seed phrases, or complete payment-card data.
• Payment, identity verification, legal commitments, sensitive personal data, or decisions beyond typed authority require a human takeover.
• The owner must end the call manually.

Test first with a number you control or a harmless public IVR. Keep the Mac and paired iPhone in view during testing.

Repository layout

skills/
  mac-phone/
    SKILL.md
    agents/openai.yaml
  phone-assistant/
    SKILL.md
    agents/openai.yaml
docs/
  audio-setup.md

License

Copyright is licensed under the GNU General Public License v3.0. See LICENSE.

This project is not affiliated with or endorsed by Apple, OpenAI, or Rogue Amoeba.