snake-ai-game/README.md

A terminal-based snake game powered by AI.

# Snake AI Game

A terminal-based snake game powered by Google's Gemini AI. Watch as an AI navigates the classic game of snake, making intelligent decisions to maximize its score.

## Features

- **AI-Powered Gameplay**: The snake is controlled by an AI using Google's Gemini model.
- **Real-time Stats**: View real-time statistics, including score, time, and token usage.
- **Executable with `npx` and `bunx`**: Easily run the game without installation.

## AI Tools

The AI interacts with the game environment using a set of specialized tools:

-   **`scan`**: This tool allows the AI to analyze the current game state, including the snake's position, food location, obstacles, and available open spaces. It helps the AI understand the environment and identify potential optimal paths.
-   **`move`**: The AI uses this tool to execute a sequence of moves (up to 5 directions) for the snake. It's how the AI controls the snake's movement on the grid.
-   **`giveUp`**: If the AI determines it's in an unwinnable situation or gets stuck, it can use this tool to gracefully end the game.

## Usage

To run the game, you need to have Node.js and `npx` (or `bun` and `bunx`) installed. You also need a Gemini API key.

You can provide your Gemini API key either as an environment variable or as a command-line option.

**Option 1: Environment Variable**

```bash
export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY"
npx snake-ai-game
```

**Option 2: Command-Line Flag**

```bash
npx snake-ai-game --apiKey="YOUR_API_KEY"
```

### Command-Line Options

-   `--apiKey`, `-k`: Your Google Generative AI API key.
-   `--help`: Show the help message.