BOB-Gemini-Free AGENTS.md

AGENTS.md — AI Agent Guidelines for BOB Gemini Free

Welcome, AI Agent! This document provides technical architecture, build instructions, directory layouts, and execution workflows for automated agents (Cursor, Windsurf, Claude Code, Codex CLI, Aider, OpenHands, Devin, Roo Code) interacting with the BOB Gemini Free codebase.

---

1. Project Overview

BOB Gemini Free (Break Ordinary Boundaries) by ABCsteps (abcsteps.com) and Divyanshu Singh Chouhan (@div197) is a high-performance, single-binary local AI gateway written in Go.

It translates three major protocol standards into Google's internal web RPC protocol (batchexecute / streamGenerateContent):

1. OpenAI Standard: POST /v1/chat/completions, POST /v1/responses (with output_text), POST /v1/tokens/count, GET /v1/models, GET /v1/models/{model}, POST /v1/images/generations
2. Anthropic Standard: POST /v1/messages (Claude Code CLI with complete SSE stream lifecycle and prompt caching counters)
3. Google Gemini Standard: GET /v1beta/models, POST /v1beta/models/{target} (including generateContent, streamGenerateContent, and :countTokens)
4. Embedded Go Library: pkg/gateway (import "github.com/div197/bob-gemini-free/pkg/gateway")

---

2. Directory & Package Structure

.
├── main.go                     # Entrypoint & CLI flag routing
├── go.mod / go.sum             # Go module definition (Go 1.26.6 in this snapshot)
├── Makefile                    # Multi-arch compilation & test commands
├── install.sh / install.ps1    # Cross-platform automated setup scripts
├── test-kit.sh / test-kit.ps1  # Automated diagnostic runners
├── pkg/
│   └── gateway/                # Exported embedded Go library (pkg/gateway)
└── internal/
    ├── browser/                # 1-click native interactive login window (CDP WebSocket)
    ├── config/                 # Configuration loader & cookie auto-discovery
    ├── diag/                   # 15-point diagnostic test kit, bench runner & e2e tests
    ├── format/                 # Protocol translation (OpenAI, Anthropic, Google, Images, Citations, Tokens)
    ├── gemini/                 # Upstream client, auth, cookie pool load-balancer, parser
    ├── models/                 # Model registry & alias catalog (Imagen 3, Nano Banana 2/Pro)
    ├── multimodal/             # Image compression, Scotty upload, token cache, dynamic refresh
    └── server/                 # HTTP mux, middleware, SSE streamer, handlers