twin

CLI tool for interacting with Google Gemini using browser session cookies (reverse-engineered web API).

Note: This project reverse-engineers Gemini's web interface. It may break if Google changes their API.

How It Works

Instead of using the official Gemini API (which requires API keys), twin:

1. Extracts your session cookies from Safari/Chrome/Firefox
2. Uses those cookies to authenticate with Gemini's web interface
3. Sends requests to the same API endpoints the web app uses

Installation

git clone https://github.com/kyupark/twin
cd twin
bun install
bun run build:binary

# Or run directly with bun
bun run dev --help

Prerequisites

You must be logged into gemini.google.com in one of these browsers:

• Safari (macOS)
• Chrome
• Firefox

Usage

Test Authentication

./twin test-auth

Send a Single Message

./twin chat "What is the capital of France?"

Interactive REPL

./twin repl

REPL commands:

• /new - Start a new conversation
• /help - Show help
• exit - Exit the REPL

Options

--psid <token>            Google __Secure-1PSID cookie value (manual override)
--cookie-source <source>  Browser to read cookies from (safari, chrome, firefox)
--chrome-profile <name>   Chrome profile name
--firefox-profile <name>  Firefox profile name
--timeout <ms>            Request timeout in milliseconds
-v, --verbose             Enable verbose output

Environment Variables

Instead of browser cookies, you can provide credentials via environment variables:

export GEMINI_PSID="your_psid_cookie_value"
./twin chat "Hello"

How Authentication Works

Google uses several cookies for session management:

Cookie	Purpose
__Secure-1PSID	Main session ID (required)
__Secure-1PSIDTS	Session timestamp
__Secure-1PSIDCC	Session control

The tool extracts these from your browser and uses them to make authenticated requests.

Limitations

• May break at any time - Google can change their API without notice
• Session expiration - Cookies expire, you'll need to re-login periodically
• Rate limits - Subject to whatever rate limits Google applies to web users
• No official support - This is not an officially supported method

Comparison with Official API

Feature	twin (cookies)	Official Gemini API
Setup	Login to browser	Get API key
Cost	Free (uses your account)	Free tier available
Stability	May break	Stable
Rate limits	Unknown	Documented
Support	None	Official

Project Structure

twin/
├── src/
│   ├── cli.ts              # CLI entry point
│   ├── cli/
│   │   └── program.ts      # Commander setup
│   ├── commands/
│   │   ├── chat.ts         # Single message command
│   │   ├── repl.ts         # Interactive REPL
│   │   └── test-auth.ts    # Auth testing
│   └── lib/
│       ├── cookies.ts      # Cookie extraction
│       ├── gemini-client.ts # API client
│       └── gemini-client-types.ts
├── package.json
└── README.md

Credits

Inspired by bird - a similar tool for Twitter/X.

License

MIT