npm package: @quantiya/codevibe-gemini-plugin
Description: Mobile companion for Gemini CLI - monitor and control your Gemini CLI sessions from your iPhone
Author: Quantiya
Latest version: 1.0.4

# CodeVibe Gemini Plugin

Mobile companion for Gemini CLI - monitor and control your Gemini CLI sessions from your iPhone.

## Overview

CodeVibe Gemini Plugin syncs your Gemini CLI sessions with the CodeVibe iOS app, allowing you to:
- **Approve or deny file edits from your phone** - See file diffs before approving
- View Gemini conversations on your phone in real-time
- Send prompts to Gemini from your iPhone
- Send image attachments from iOS (Gemini analyzes them)
- Monitor multiple coding sessions from anywhere
- Works alongside Claude Code sessions in the same app

## Prerequisites

- **macOS** (required for tmux integration)
- **Node.js 18+**
- **tmux** (`brew install tmux`)
- **Gemini CLI** installed and authenticated
- **CodeVibe iOS app** installed on your iPhone

## Installation

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

### From Source (Development)

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

## Usage

### First Time Setup

```bash
# Authenticate with backend (opens browser for Sign in with Apple/Google)
codevibe-gemini login

# Check authentication status
codevibe-gemini status
```

### Running the Plugin

```bash
# Start Gemini with mobile sync
codevibe-gemini
```

The plugin will automatically detect Gemini sessions and sync conversations to your iOS app.

### CLI Commands

| Command | Description |
|---------|-------------|
| `codevibe-gemini` | Start Gemini with mobile sync |
| `codevibe-gemini login` | Authenticate with backend |
| `codevibe-gemini logout` | Clear stored credentials |
| `codevibe-gemini status` | Show authentication status |

## How It Works

This plugin uses Gemini CLI's hook system (available in stable releases since December 2025) combined with transcript file watching for complete coverage.

**Hook Integration:**
1. **BeforeTool** - Captures tool approval requests, shows file diffs on iOS, waits for your approval
2. **AfterTool** - Captures tool execution results
3. **SessionStart/SessionEnd** - Manages session lifecycle

**Transcript Watching:**
- Monitors `~/.gemini/tmp/*/chats/` for user prompts and assistant responses
- Provides accurate timestamps for event ordering

**Mobile Integration:**
- Receives prompts from iOS app via WebSocket subscriptions
- Executes prompts using tmux send-keys (works even when screen is locked)

## Known Limitations

- **macOS only**: Requires tmux for terminal integration
- **Gemini CLI version**: Hooks require December 2025+ stable release

## Features

| Feature | Status | Notes |
|---------|--------|-------|
| Interactive prompts | ✅ Full | Approve/deny from iOS with file diff preview |
| User prompts | ✅ Full | Real-time sync to iOS |
| Assistant responses | ✅ Full | Real-time sync to iOS |
| File diffs | ✅ Full | Preview changes before approving |
| Tool results | ✅ Full | See what Gemini executed |
| Image attachments | ✅ Full | Send images from iOS, uses `@./path` format |
| Mobile prompts | ✅ Full | Send prompts from iOS, auto-submits |

**Full feature parity with Claude Code plugin.**

## Related

- **CodeVibe iOS App** - Available on the App Store
- [CodeVibe Claude Plugin](https://github.com/hendryyeh/codevibe-claude-plugin) - For Claude Code
- [CodeVibe Codex Plugin](https://github.com/hendryyeh/codevibe-codex-plugin) - For OpenAI Codex CLI

## License

MIT License - See [LICENSE](LICENSE) for details.

## Support

- **Issues:** [GitHub Issues](https://github.com/hendryyeh/quantiya-codevibe-gemini-plugin/issues)
- **Email:** support@quantiya.ai