# open-gemini

Use your own signed-in Gemini web account from a local CLI, MCP server, or loopback HTTP bridge. It automates the Gemini web app through Chrome; it does not use the Gemini API and does not require a Google API key. Your Google account and plan determine which models and features are available. This project does not unlock paid features or quotas.

## Requirements and setup

- Node.js 22 or later
- Google Chrome installed
- A Google account that can use [Gemini](https://gemini.google.com/)

Clone the repository and install its locked dependencies:

```sh
git clone https://github.com/mkshaonexe/open-gemini.git
cd open-gemini
npm ci
```

Sign in once through the normal Chrome window that open-gemini opens, then check the account:

```sh
node bin/cli.js login
node bin/cli.js status
node bin/cli.js capabilities
node bin/cli.js models
```

After sign-in, ordinary commands launch Chrome headlessly using the saved profile. This is still a browser runtime: keep the profile available and do not open it in another Chrome process while open-gemini is using it.

## CLI examples

```sh
node bin/cli.js ask "Explain this topic in three paragraphs"
node bin/cli.js ask "Summarize this file" --file ./report.pdf
node bin/cli.js ask "Make an image of a red fox in snow" --tool image
node bin/cli.js ask "Plan a short video about a solar eclipse" --tool video
node bin/cli.js ask "Compose a calm piano theme" --tool music
node bin/cli.js ask "Research recent battery recycling methods" --tool research
node bin/cli.js history --limit 10
node bin/cli.js conversation CONVERSATION_ID
node bin/cli.js usage
```

`ask` prints the answer text when present. Use `call` with JSON when you need the complete structured result, including media URLs or returned metadata:

```sh
node bin/cli.js call ask --json '{"prompt":"Make an image of a red fox in snow","tool":"image"}'
```

The `--tool` options are `image`, `video`, `music`, `canvas`, and `research`. Check `capabilities` and `models` for what the current account exposes. Availability can change with account, plan, location, device, and rollout.

## MCP

For an MCP host that supports a local stdio server, add a server entry using the absolute path to this checkout:

```json
{
  "mcpServers": {
    "open-gemini": {
      "command": "node",
      "args": ["/absolute/path/open-gemini/bin/cli.js", "mcp"]
    }
  }
}
```

Replace `/absolute/path/open-gemini` with the actual checkout directory. Configuration syntax varies by host, so translate this standard stdio server entry if needed. Complete `node bin/cli.js login` first. The MCP server exposes the methods in the account bridge, including `gemini_status`, `gemini_capabilities`, `gemini_models`, `gemini_ask`, history/conversation operations, memory operations, usage, and download. Destructive conversation or memory deletion requires `confirm: true`.

Claude, Codex, and other agents can use the same standard stdio MCP configuration when their host supports it. Hermes or OpenClaw can connect through standard MCP if the installed host supports MCP; otherwise use the CLI workflow in [`skills/open-gemini/SKILL.md`](skills/open-gemini/SKILL.md). This repository does not install a host-specific plugin.

## Long-running work and local HTTP bridge

For longer generation or research requests, start the server in a terminal:

```sh
node bin/cli.js serve
```

Then submit and poll a job from another terminal:

```sh
node bin/cli.js jobs start ask --json '{"prompt":"Research this topic","tool":"research"}'
node bin/cli.js jobs JOB_ID
```

The server remains attached to one Chrome runtime. Stop it with Ctrl-C. A timed-out request may still have completed in Gemini; inspect its conversation or job state before retrying to avoid duplicate work.

The HTTP API listens on `127.0.0.1` by default and requires a generated bearer key. Get the local key only when configuring a trusted local client:

```sh
node bin/cli.js key
```

Keep this key private. It authorizes local API access and is separate from Google account credentials. The HTTP bridge limits JSON request bodies to 1 MiB and keeps a bounded, in-memory job queue of up to 100 jobs. Job state is not durable storage. The optional OpenAI-compatible routes expose model listing and one non-streaming, plain-text user message. They do not support streaming, tool calls, other message roles, or generation parameters.

## Configuration

Configuration is stored under `~/.open-gemini` by default. Environment variables can override it:

| Variable | Purpose |
| --- | --- |
| `OPEN_GEMINI_HOME` | Configuration, profile, and downloads directory |
| `OPEN_GEMINI_PROFILE` | Chrome profile directory |
| `CHROME_PATH` | Chrome executable path |
| `OPEN_GEMINI_PORT` | Local HTTP API port (default `2792`) |
| `OPEN_GEMINI_CDP_PORT` | Local Chrome debugging port (default `9342`) |
| `OPEN_GEMINI_ACCOUNT` | Gemini account index in the browser URL (default `0`) |
| `OPEN_GEMINI_API_KEY` | Override the generated local HTTP bearer key |
| `OPEN_GEMINI_HEADLESS` | Set to `false` to show Chrome during ordinary commands |
| `OPEN_GEMINI_CDP_URL` | Connect to an existing loopback Chrome debugging endpoint |
| `OPEN_GEMINI_TIMEOUT_MS` | Default request timeout in milliseconds |
| `OPEN_GEMINI_URL` | Point CLI commands to an already-running local bridge |

`npm link` is optional if you want the local checkout’s `open-gemini` command on your PATH. The project is used from source; this README does not promise an npm registry installation.

## Troubleshooting

- If `login` cannot open Chrome, install Chrome or set `CHROME_PATH` to its executable.
- If Gemini still shows a sign-in page, complete sign-in in the Chrome window opened by `login`, then run `status` again.
- If you see `PROFILE_BUSY`, another open-gemini process owns that profile. Use `OPEN_GEMINI_URL` to connect to its running server, or stop it before starting another command.
- If the Chrome debugging port is already in use, choose another `OPEN_GEMINI_CDP_PORT`.
- If a model or feature is unavailable, check `capabilities`, `models`, and `usage`; account eligibility and usage limits are controlled by Google.

See [Gemini feature inventory](docs/gemini-feature-inventory.md) and [plans and limits](docs/plans-and-limits.md) for official references and scope notes.