Gemini CLI Core Package Codelab

Welcome to the Gemini CLI Core Package codelab! This hands-on tutorial will teach you how to use the core package to build your own application powered by Gemini CLI's coding agent.

📋 Prerequisites

• Node.js 18+ installed
• Basic TypeScript/JavaScript knowledge
• Gemini API key (get one at https://aistudio.google.com/app/apikey)

🚀 Getting Started

1. Install Dependencies

# Clone this codelab repository
git clone <your-codelab-repo>
cd gemini-cli-core-codelab

# Install all dependencies including @google/gemini-cli-core
npm install

2. Set Your API Key

export GEMINI_API_KEY="your-api-key-here"

📚 Codelab Steps

Step 1: Hello World (5 min)

Learn the basics of setting up the core package and sending your first message.

npm run step1

Key concepts:

• Creating a Config instance with sessionId
• Authentication with AuthType.USE_GEMINI
• Sending messages with chat.sendMessage()
• Getting response text and metadata

Step 2: Streaming and Thinking (5 min)

Implement real-time streaming responses with thinking display.

npm run step2

Key concepts:

• Using sendMessageStream() for real-time responses
• Detecting and displaying AI thinking (part.thought === true)
• Processing streaming events
• Handling text output character by character

Step 3: Built-in Tools - Detection and Execution (5 min)

Learn how Gemini detects when tools are needed and execute them directly.

npm run step3

Key concepts:

• Configuring coreTools: ['read_file', 'write_file', 'list_directory']
• Tool detection from streaming responses
• Direct tool execution with executeToolCall()
• Handling FunctionCall objects and tool results

Step 4: Tool Approvals with CoreToolScheduler (5 min)

Implement approval flows for sensitive operations using CoreToolScheduler.

npm run step4

Key concepts:

• Creating and configuring CoreToolScheduler
• Handling tool approval prompts
• ToolConfirmationOutcome options (ProceedOnce, ProceedAlwaysTool, Cancel)
• Managing tool execution lifecycle

📚 Resources

• Gemini CLI Launch Blog Post
• Gemini CLI GitHub Repository
• @google/gemini-cli-core on npm