CodeVibe Codex Plugin

Mobile companion plugin for OpenAI Codex CLI. Monitor and interact with your Codex sessions from your iPhone.

Overview

This plugin enables bidirectional synchronization between Codex CLI on your Mac and the CodeVibe iOS app. See your conversations, shell commands, file edits, and agent reasoning in real-time on your phone.

Part of the CodeVibe multi-agent ecosystem:

• Claude Plugin - For Claude Code
• Gemini Plugin - For Gemini CLI
• Codex Plugin (this repo) - For OpenAI Codex CLI

Quick Start

npm install -g @quantiya/codevibe-codex-plugin
codevibe-codex login   # authenticate with CodeVibe backend
codevibe-codex         # start Codex with mobile sync

Features

| Feature | Supported | |---------|-----------| | User prompts | Yes | | Assistant responses | Yes | | Agent reasoning/thinking | Yes | | Shell commands | Yes | | File edits (patches) | Yes | | Tool outputs | Yes | | Image attachments | Yes | | Approval prompts | Yes (via tmux pane detection) | | File diff preview | Yes |

What gets synced

• Desktop → Mobile: user prompts, assistant responses, shell commands, tool/file edits, approval prompts, images, logs
• Mobile → Desktop: text prompts and approval responses sent from iOS app into the active Codex session (via tmux)

Prerequisites

• macOS
• Node.js 18+
• tmux (brew install tmux)
• Codex CLI installed and authenticated
• CodeVibe iOS app

Installation

npm install -g @quantiya/codevibe-codex-plugin

From Source (Development)

git clone https://github.com/hendryyeh/quantiya-codevibe-codex-plugin.git
cd codevibe-codex-plugin
npm install
npm run build

Usage

Use codevibe-codex instead of codex to enable mobile sync:

# Start Codex with mobile sync
codevibe-codex

# Start with an initial prompt
codevibe-codex "fix the bug in auth.ts"

CLI Commands

codevibe-codex login   # Authenticate with CodeVibe backend
codevibe-codex status  # Check authentication status
codevibe-codex logout  # Sign out
codevibe-codex         # Start Codex with mobile sync

How It Works

1. Session Log Watching - Monitors ~/.codex/sessions/ for JSONL log files
2. Real-time Sync - Parses log entries and syncs to AWS AppSync backend
3. Mobile Display - iOS app receives events via WebSocket subscription
4. Mobile Input - Messages from iOS are sent to terminal via tmux

Each live Codex process appears as its own CodeVibe session, even if multiple Codex sessions are running in the same project directory.

Data Flow

Desktop → Mobile:
Codex CLI → Session JSONL → Plugin → AppSync → iOS App

Mobile → Desktop:
iOS App → AppSync → Plugin → tmux send-keys → Codex CLI

Configuration

Create a .env.development file (see .env.example):

# AWS AppSync
APPSYNC_URL=https://xxx.appsync-api.us-east-1.amazonaws.com/graphql
APPSYNC_REALTIME_URL=wss://xxx.appsync-realtime-api.us-east-1.amazonaws.com/graphql

# Cognito
COGNITO_USER_POOL_ID=us-east-1_xxx
COGNITO_CLIENT_ID=xxx
COGNITO_DOMAIN=xxx.auth.us-east-1.amazoncognito.com

Troubleshooting

Session not appearing in iOS app

# Check if session logs exist
ls -la ~/.codex/sessions/$(date +%Y)/$(date +%m)/$(date +%d)/

# Check plugin logs
tail -f /tmp/codevibe-codex-mcp.log

Mobile prompts not working

# Verify tmux session exists
tmux list-sessions | grep codevibe-codex

Known Limitations

• Approval prompts are not in JSONL logs - Detected via tmux pane observation instead of structured log entries
• macOS only - Requires tmux for terminal integration

Related

• CodeVibe iOS App - Available on the App Store
• Claude Plugin - For Claude Code
• Gemini Plugin - For Gemini CLI

License

MIT

Maintained by: CodeVibe Team