consortium/README.md

Remote control and session sharing CLI for AI coding agents

# Consortium

Code on the go — control AI coding agents from your mobile device.

Free. Open source. Code anywhere.

## Installation

```bash
npm install -g consortium
```

## Usage

### Claude (default)

```bash
consortium
```

This will:
1. Start a Claude Code session
2. Display a QR code to connect from your mobile device
3. Allow real-time session sharing between Claude Code and your mobile app

### Gemini

```bash
consortium gemini
```

Start a Gemini CLI session with remote control capabilities.

**First time setup:**
```bash
# Authenticate with Google
consortium connect gemini
```

## Commands

### Main Commands

- `consortium` – Start Claude Code session (default)
- `consortium gemini` – Start Gemini CLI session
- `consortium codex` – Start Codex mode

### Utility Commands

- `consortium auth` – Manage authentication
- `consortium connect` – Store AI vendor API keys in Consortium cloud
- `consortium notify` – Send a push notification to your devices
- `consortium daemon` – Manage background service
- `consortium doctor` – System diagnostics & troubleshooting

### Connect Subcommands

```bash
consortium connect gemini     # Authenticate with Google for Gemini
consortium connect claude     # Authenticate with Anthropic
consortium connect codex      # Authenticate with OpenAI
consortium connect status     # Show connection status for all vendors
```

### Gemini Subcommands

```bash
consortium gemini                      # Start Gemini session
consortium gemini model set <model>    # Set default model
consortium gemini model get            # Show current model
consortium gemini project set <id>     # Set Google Cloud Project ID (for Workspace accounts)
consortium gemini project get          # Show current Google Cloud Project ID
```

**Available models:** `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`

## Options

### Claude Options

- `-m, --model <model>` - Claude model to use (default: sonnet)
- `-p, --permission-mode <mode>` - Permission mode: auto, default, or plan
- `--claude-env KEY=VALUE` - Set environment variable for Claude Code
- `--claude-arg ARG` - Pass additional argument to Claude CLI

### Global Options

- `-h, --help` - Show help
- `-v, --version` - Show version

## Environment Variables

### Consortium Configuration

- `CONSORTIUM_SERVER_URL` - Custom server URL (default: https://api.consortium.dev)
- `CONSORTIUM_WEBAPP_URL` - Custom web app URL (default: https://app.consortium.dev)
- `CONSORTIUM_HOME_DIR` - Custom home directory for Consortium data (default: ~/.consortium)
- `CONSORTIUM_DISABLE_CAFFEINATE` - Disable macOS sleep prevention (set to `true`, `1`, or `yes`)
- `CONSORTIUM_EXPERIMENTAL` - Enable experimental features (set to `true`, `1`, or `yes`)

### Gemini Configuration

- `GEMINI_MODEL` - Override default Gemini model
- `GOOGLE_CLOUD_PROJECT` - Google Cloud Project ID (required for Workspace accounts)

## Gemini Authentication

### Personal Google Account

Personal Gmail accounts work out of the box:

```bash
consortium connect gemini
consortium gemini
```

### Google Workspace Account

Google Workspace (organization) accounts require a Google Cloud Project:

1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
2. Enable the Gemini API
3. Set the project ID:

```bash
consortium gemini project set your-project-id
```

Or use environment variable:
```bash
GOOGLE_CLOUD_PROJECT=your-project-id consortium gemini
```

**Guide:** https://goo.gle/gemini-cli-auth-docs#workspace-gca

## Contributing

Interested in contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## Requirements

- Node.js >= 20.0.0

### For Claude

- Claude CLI installed & logged in (`claude` command available in PATH)

### For Gemini

- Gemini CLI installed (`npm install -g @google/gemini-cli`)
- Google account authenticated via `consortium connect gemini`

## License

MIT