npm package: @quantiya/codevibe-claude-plugin
Description: Mobile companion for Claude Code - monitor and control your Claude Code sessions from your iPhone with CodeVibe
Author: Quantiya
Latest version: 1.0.8

# CodeVibe Claude Plugin

Control Claude Code from your iPhone with real-time bidirectional synchronization. This plugin enables seamless communication between your desktop Claude Code sessions and the CodeVibe iOS app.

## Features

- **Real-time Sync** - See desktop conversations on mobile instantly (~100-500ms latency)
- **Mobile Control** - Send prompts from your iPhone that execute in the correct desktop session
- **Locked Screen Support** - Works even when your Mac screen is locked (via tmux)
- **Interactive Prompts** - Answer permission dialogs with numbered options (1=Yes, 2=Yes for project, 3=Reject)
- **Voice Input** - Dictate prompts using iOS speech-to-text
- **Image Attachments** - Send screenshots and photos with your messages
- **Markdown Rendering** - Code blocks and formatting displayed beautifully
- **Secure** - Uses AWS AppSync with Cognito authentication (Sign in with Apple/Google)
- **Complete Capture** - Syncs user prompts, assistant responses, tool usage, and file changes
- **Session-Aware** - Multiple Claude Code sessions work independently
- **Auto-execution** - Mobile prompts execute immediately (same trust model as desktop)

## Prerequisites

- **macOS** (darwin platform)
- **Node.js** 18.0.0 or higher
- **tmux** (for locked screen support): `brew install tmux`
- **Claude Code** with plugin system enabled

## Installation

### Step 1: Install Wrapper Command (One-time)

Install the CodeVibe wrapper command via npm:

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

This puts `codevibe-claude` (and `codevibe-gemini`, `codevibe-codex`) in your PATH.

### Step 2: Register MCP Plugin (One-time)

Claude Code also needs its MCP plugin registered. Inside a Claude Code session, run:

```
/plugin marketplace add https://github.com/hendryyeh/quantiya-codevibe-marketplace
```

Then:

```
/plugin install codevibe-claude
```

### Step 3: Authenticate (One-time)

Login to your CodeVibe account:

```bash
codevibe-claude login
```

This opens a browser for OAuth authentication (Sign in with Apple or Google). Your tokens are stored securely in `~/.codevibe-claude/`.

Other auth commands:
```bash
codevibe-claude status   # Check authentication status
codevibe-claude logout   # Sign out and clear tokens
```

### Step 5: Start Claude Code with Mobile Support

**Important:** You must use the `codevibe-claude` wrapper instead of `claude` directly:

```bash
codevibe-claude
```

This wrapper:
- Creates a tmux session for the Claude Code instance
- Enables mobile prompts to work even when your Mac screen is locked
- Supports multiple concurrent Claude Code sessions

**Note:** Running `claude` directly without the wrapper will prevent mobile prompts from working when your screen is locked.

### Step 6: Download the iOS App

Download "CodeVibe" from the App Store and sign in with the same account you used in Step 4.

## Usage

### Using the `codevibe-claude` Wrapper

```bash
# Start a new session (same as running `claude`)
codevibe-claude

# Resume the last session
codevibe-claude --resume

# Start with a prompt
codevibe-claude -p "fix the bug"

# All other claude arguments work too
codevibe-claude --model sonnet
```

### Benefits of `codevibe-claude`

| Feature | `codevibe-claude` | Regular `claude` |
|---------|-------------------|------------------|
| Mobile prompts | Works always | Only when screen unlocked |
| Screen locked support | Yes (via tmux) | No |
| Mouse scrolling | Yes | Yes |
| Same experience | Yes | Yes |

### Desktop to Mobile Sync

Everything you do in Claude Code is automatically synced to mobile:

- **User Prompts** - Your questions and commands
- **Assistant Responses** - Claude's complete responses
- **Tool Usage** - File edits, reads, writes
- **Interactive Prompts** - Y/n permission requests
- **Notifications** - System messages

### Mobile to Desktop Control

From the iOS app:

1. Open the CodeVibe app
2. Select your active session
3. Type a message or response
4. It executes immediately in your desktop Claude Code session
5. See the response on both desktop and mobile

### Responding to Permission Prompts from Mobile

When Claude needs permission to edit or write files, you can respond directly from your iPhone.

**Available Options:**

| Reply | Description |
|-------|-------------|
| `1` | **Approve** - Allow this specific file operation |
| `2` | **Always Allow** - Approve and skip future prompts for this project |
| `3` | **Reject** - Decline the operation |
| `3 <message>` | **Reject with Instructions** - Decline and tell Claude what to do instead |

**Examples:**
```
1                          -> Approves the edit
2                          -> Approves and trusts this project
3                          -> Rejects the edit
3 use a different approach -> Rejects and redirects Claude
```

**Other Inputs:**
- `Y` / `N` - For yes/no confirmation prompts
- `exit`, `quit` - To cancel running operations
- Any other text - Sent as a new prompt to Claude

## Troubleshooting

### "codevibe-claude: command not found"

**Cause:** PATH not updated or shell not reloaded.

**Solution:**
```bash
source ~/.zshrc  # or ~/.bashrc
```

Or check if PATH was added:
```bash
grep "codevibe-claude" ~/.zshrc
```

### "Not authenticated" error

**Cause:** User hasn't logged in or tokens expired.

**Solution:**
```bash
codevibe-claude login
```

### Mobile messages not executing

**Cause:** Not using the codevibe-claude wrapper.

**Solution:** Start Claude Code with:
```bash
codevibe-claude
```
Not just `claude`.

### Plugin hooks not firing

**Cause:** Plugin not properly installed.

**Solution:**
```
# In Claude Code
/plugin list              # Check if installed
/plugin uninstall codevibe-claude
/plugin install codevibe-claude
```

### Port already in use

**Error:** `EADDRINUSE: address already in use :::3456`

**Solution:** Another MCP server is already running. Kill it:

```bash
pkill -f "node dist/server.js"
```

## Mac Power Settings (for Locked Screen Support)

To ensure mobile prompts work when your Mac screen is locked:

1. **System Settings** -> **Battery** (or **Energy**) -> Set "Computer sleep" to **Never** (when on power)
2. In Terminal:
   ```bash
   sudo pmset -a tcpkeepalive 1
   sudo pmset -a womp 1
   ```

This keeps network connections alive during sleep.

## Architecture

```
Desktop -> Mobile:
+-------------+    +----------+    +---------+    +----------+    +--------+
| Claude Code | -> |   Hook   | -> |   MCP   | -> | AppSync  | -> | Mobile |
|             |    | Scripts  |    | Server  |    | GraphQL  |    |  App   |
+-------------+    +----------+    +---------+    +----------+    +--------+

Mobile -> Desktop:
+--------+    +----------+    +---------+    +-------------+
| Mobile | -> | AppSync  | -> |   MCP   | -> | Claude Code |
|  App   |    | GraphQL  |    | Server  |    | (tmux keys) |
+--------+    +----------+    +---------+    +-------------+
```

## Development

If you want to contribute or run from source:

### Clone and Build

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

### Local Testing

For local development and testing:

```bash
./install-local.sh

# In Claude Code
/plugin marketplace add ./dev-marketplace
/plugin install codevibe-claude@codevibe-claude-dev
```

### View Logs

```bash
# MCP Server logs
tail -f /tmp/codevibe-claude-mcp.log

# Hook scripts logs
tail -f /tmp/codevibe-claude-hooks.log
```

## Support

- **Issues:** [GitHub Issues](https://github.com/hendryyeh/quantiya-codevibe-claude-plugin/issues)

## Related

- **CodeVibe iOS App** - Available on the App Store

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Made with care by the CodeVibe Team**