codevibe-codex-plugin

CodeVibe Codex Plugin

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

Last updated: 2025-12-14

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

git clone https://github.com/hendryyeh/quantiya-codevibe-codex-plugin.git
cd codevibe-codex-plugin
npm install
npm run build
./bin/codevibe-codex login   # authenticate with CodeVibe backend
./bin/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	No*

*Codex CLI doesn't log approval prompts to session files

What gets synced

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

Prerequisites

• macOS
• Node.js 18+
• Codex CLI installed and authenticated
• CodeVibe iOS app

Installation

# Clone the repository
git clone https://github.com/hendryyeh/quantiya-codevibe-codex-plugin.git
cd codevibe-codex-plugin

# Install dependencies
npm install

# Build
npm run build

# Authenticate with CodeVibe backend
./bin/codevibe-codex login

Usage

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

# Start Codex with mobile sync
./bin/codevibe-codex

# Start with an initial prompt
./bin/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

• Session Log Watching - Monitors ~/.codex/sessions/ for JSONL log files
• Real-time Sync - Parses log entries and syncs to AWS AppSync backend
• Mobile Display - iOS app receives events via WebSocket subscription
• 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 present in JSONL logs - When Codex asks "Apply this change? [y/n]", the structured prompt is still terminal-native
• Prompt detection depends on tmux rendering - The plugin now inspects the live tmux pane to improve approval handling, but the source log still does not contain a structured approval event

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