npm package: @quantiya/codevibe-codex-plugin
Description: Mobile companion for OpenAI Codex CLI - monitor and control your Codex CLI sessions from your iPhone
Author: Quantiya
Latest version: 1.0.5

# CodeVibe Codex Plugin

Last updated: 2026-03-24

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](https://github.com/hendryyeh/quantiya-codevibe-claude-plugin) - For Claude Code
- [Gemini Plugin](https://github.com/hendryyeh/quantiya-codevibe-gemini-plugin) - For Gemini CLI
- **Codex Plugin** (this repo) - For OpenAI Codex CLI

## Quick Start

```bash
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](https://github.com/openai/codex) installed and authenticated
- CodeVibe iOS app

## Installation

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

### From Source (Development)

```bash
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:

```bash
# Start Codex with mobile sync
codevibe-codex

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

### CLI Commands

```bash
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`):

```bash
# 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

```bash
# 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

```bash
# 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](https://github.com/hendryyeh/codevibe-claude-plugin) - For Claude Code
- [Gemini Plugin](https://github.com/hendryyeh/codevibe-gemini-plugin) - For Gemini CLI

## License

MIT

---

**Maintained by:** CodeVibe Team
**Last Updated:** 2026-03-24