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

## Migrating from `consortium-local`

`consortium-local` was the original entry point for launching Consortium Code
against the local agent. It still ships as a thin shim that prints a deprecation
banner and forwards to `consortium code`, but it will be removed in the next
major release. Update any scripts, aliases, or CI jobs to use the new surface:

```bash
# Before
consortium-local            # auto-launch Consortium Code
consortium-local --resume <id>

# After
consortium code             # direct launch of Consortium Code
consortium code --resume <id>

# Or — if you want the new no-args interactive menu:
consortium                  # opens the TUI
```

The new top-level surface adds:

- `consortium` — interactive menu (no-args default) covering Consortium Code,
  session management, register-machine, switch-workspace, daemon control, and
  auth. See `consortium --help` for keyboard shortcuts.
- `consortium code [--resume <id>]` — direct launch (what `consortium-local`
  used to do).
- `consortium switch-org [--org <slug>]` — change the active workspace.
- `consortium whoami [--json]` — print the current auth / workspace context.

If you run `consortium-local` in automation and can't tolerate the banner on
stderr, set `CONSORTIUM_HIDE_DEPRECATION_WARNING=1` to silence it while you
migrate.

## Troubleshooting

If the CLI exits silently, fails to launch, or reports an unsupported platform, run `consortium doctor` and follow the guide at [docs/cli-troubleshooting.md](../../docs/cli-troubleshooting.md). Common fixes:

- **musl / Alpine / old glibc** — run the pre-built docker image: `docker run -it --rm -v "$PWD":/workspace -v "$HOME/.consortium":/root/.consortium ghcr.io/consortium/cli:stable`
- **`EACCES` during install** — `npm install -g --unsafe-perm consortium`
- **Wrong arch** — `npm install -g consortium-code-$(node -p "process.platform + '-' + process.arch")`
- **Headless server / auth hangs** — `consortium auth login` (device-code flow)

Logs live in `~/.consortium/logs/` (boot trace, launch preflight, crash dumps, daemon logs).

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