Plan and Build Apps with Gemini CLI Conductor

1. Introduction

In this codelab, you will learn how to plan and build software applications with the Gemini CLI Conductor extension. You will start by building a "greenfield" application completely from scratch. Then, you will treat it as a "brownfield" project, iterating on it to add authentication and storage.

What you'll do

• Install Gemini CLI and the Conductor extension
• Build a "Picker Wheel" web app from scratch using Conductor's planning and implementation capabilities
• Add personalization to the application by adding authentication and storage using Firebase

What you'll learn

• How to use the Conductor extension to plan, implement, and review a "greenfield" application
• How to use the Conductor extension to add features to a "brownfield" application

What you'll need

• A web browser such as Chrome
• A Google Cloud project with billing enabled
• Node.js installed (version 18+ recommended)
• A Local code editor like Visual Studio Code

2. Before you begin

Create a Google Cloud Project

1. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
2. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

Start Cloud Shell

Using Cloud Shell allows us to complete this section without having to install the gcloud and firebase CLI tools locally.

Cloud Shell is a command-line environment running in Google Cloud that comes preloaded with necessary tools.

1. Click Activate Cloud Shell at the top of the Google Cloud console.
2. Once connected to Cloud Shell, verify your authentication:

   gcloud auth list
   

3. Confirm your project is configured:

   gcloud config get project
   

4. If your project is not set as expected, set it:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

Enable APIs

Enable the Firebase Management API in your Google Cloud project.

gcloud services enable firebase.googleapis.com

Add Firebase to your project

The Firebase CLI comes pre-installed in Cloud Shell. From Cloud Shell, sign in with the same Google Account that gives you access to the Google Cloud project. If you are working locally, install the Firebase CLI by following the instructions.

firebase login

Run the following command to add Firebase to your Google Cloud project:

firebase projects:addfirebase

If this is your first time running the firebase CLI, answer any questions that you are asked.

Exit Cloud Shell

You may close the Cloud Shell window. In the following section we'll configure your local environment.

3. Install Gemini CLI and Conductor locally

In this step, you will prepare your local development environment by installing Gemini CLI and the Conductor extension using your local code editor and terminal.

Install Gemini CLI

1. Install the latest version of the Gemini CLI globally using npm:

   npm install -g @google/gemini-cli
   

   If you see permission errors, you may need to use a version manager like nvm, or run this command as root using sudo.

2. Restart your terminal so that gemini is added to your PATH.
3. Verify the installation has installed the latest version:

   gemini --version
   

4. Create and change to a new project directory: In a later section we'll create a project in a picker-wheel directory. Create that directory now and change to this directory:

   mkdir picker-wheel
   cd picker-wheel
   

5. Authenticate:
   • Start Gemini CLI.

     gemini
     

   • When asked "Do you trust the files in this folder?", select Trust folder (picker-wheel)
   • When asked "How would you like to authenticate for this project?", select Vertex AI. Follow the authentication guide to obtain a Google Cloud API key and set the GOOGLE_API_KEY environment variable. Take a moment to explore different usage tiers and their corresponding API rate limits.
6. Exit Gemini CLI: Type /quit from the CLI terminal to end your live Gemini CLI session before continuing.

Install Conductor Extension

Conductor is a Google-built, open-source Gemini CLI extension that enables context-driven development features like planning and implementation tracking.

1. Install the extension:

   gemini extensions install https://github.com/gemini-cli-extensions/conductor
   

2. Verify the installation:
   • Start Gemini CLI.

     gemini
     

   • Type /conductor and you will see a list of commands like setup, newTrack, implement, etc.
3. Exit Gemini CLI: Type /quit from the CLI terminal to end your live Gemini CLI session before continuing.

4. Greenfield Development: The Picker Wheel

Now that your environment is set up, you will build a new application from scratch. You'll create a "Picker Wheel" — a lightweight web app that spins to select a random option.

Setup Product Context

1. Confirm you are in the picker-wheel directory you created in the previous section:

   pwd
   

2. Start Gemini CLI: Start a new Gemini CLI session from your project directory.

   gemini
   

3. Initialize Conductor: Run the setup command to scaffold the project and set up the Conductor environment.

   /conductor:setup
   

4. Follow the interactive prompts: The interactive prompts you see will not match these examples exactly. Focus a simpler design to familiarize yourself with the Conductor workflow.
   • Product goal: A web application that displays a configurable spinning wheel to select a random item from a list.
     • Target Audience → General Public
     • Interaction → Tap/Click to Spin
     • Customization → Basic
     • Platform → Desktop-First
   • Product guidelines: Autogenerate.
   • Tech stack:
     • Languages → TypeScript/JavaScript - Ideal for full-stack web
     • Frontend → Vue.js - Intuitive web interfaces
     • Backend → Express.js - Fast Node backend
     • Database → None - No database needed
   • Workflow: Standard.
   • Product requirements:
     • User Stories → Customizable Options, Clear Winner Display
     • Key Features → Editable Option List, Randomized Colors
     • Constraints → Client-Side Only, High Performance
     • Non-Functional → High Test Coverage, TypeScript & Vue.js, Responsive Design
   Conductor will generate context files in a conductor/ directory.

Create a New Track

A "Track" in Conductor represents a feature or a unit of work.

1. Start a new track using /conductor:newTrack. Conductor might propose an initial track based on the product context. Alternatively, you can propose your own or ask conductor to suggest a track.
2. Review the generated plan: Conductor will generate an index.md, a spec.md, and a plan.md inside conductor/tracks/{track-id}/. Take a moment to read them. If everything looks good, Conductor will prompt you to save and commit the initial setup files.

Implement the Track

1. Start implementation:

   /conductor:implement
   

   Conductor will now work through the plan, writing code for the project.

   Tip: To avoid getting stuck on interactive shells or long-running processes (like dev servers or test watchers), we need to ensure that Conductor knows exactly how to handle these specific commands. Tools like Vite (npm run dev) and Vitest (npm run test) often run in "watch mode" by default, which keeps the process open indefinitely. You can instruct Conductor to disable watch mode or use is_background: true when executing commands by updating workflow.md.

2. Verify the application: Throughout the implementation phase, Conductor will prompt you to manually test the application. For example, it will ask you to open the local web server, preview the application in your browser, and verify the changes. When the implementation is complete, you should see a functional picker wheel.

   Troubleshooting: If the generated code behaves unexpectedly, check the conductor/tracks/.../plan.md for any skipped steps or errors.

3. Review the implementation: As a last step, you can ask Conductor to review the implementation. It should review the source code, synchronize the project documentation, and archive the track.

   /conductor:review
   

5. Brownfield Iteration: Add Personalization

Now you will pivot to "brownfield" development. You will improve the picker wheel web application from the previous section so that signed-in users can save and restore their picker wheel configurations.

If you want to jump straight into a brownfield application, you can download the golden code from the last section for a reference implementation and continue building on it.

Create a Personalization Track

1. In the following "brownfield" example, we will use Firebase for authentication and storage. Install the Gemini CLI Firebase extension so Conductor can use it.

   gemini extensions install https://github.com/firebase/agent-skills
   

2. Start Gemini CLI: Start a new Gemini CLI session from your project directory.

   gemini
   

3. Start a new track: Start a new track.

   /conductor:newTrack "I want users to be able to log in to their accounts and
   save their picker wheel configurations."
   

4. Follow the interactive prompts: The interactive prompts you see will not match these examples exactly. Focus a simpler design to familiarize yourself with the Conductor workflow.
   • Track goal:
     • Auth Provider → Firebase Auth
     • Saved Configs → Wheel Options
     • Data Storage → Firestore
     • Firestore Login UI → Modal Overlay
   Conductor will generate context files for a new track inside conductor/tracks/{track-id}.
5. Review the generated plan: Take a moment to read a index.md, a spec.md, and a plan.md inside conductor/tracks/{track-id}/.

   Tip: You are encouraged to converse with Gemini to understand and discuss the plan as much as possible before moving on to implementation.

6. Implement: If everything looks good, you can start the implementation.

   /conductor:implement
   

7. Verify: Reload your application. You should see an updated application.

   In case the AI gets stuck with testing the authentication implementation, remember to enable Google Sign-In in the Firebase Console under Authentication > Sign-in method.

   

Here is the golden code for a reference implementation. You must provide your Firebase project in .firebaserc and your Firebase configurations in firebase.ts to start your application properly.

6. Clean up

To avoid ongoing charges to your Google Cloud account, delete the resources created during this codelab.

Delete the Firebase Project (and Google Cloud Project)

The easiest way to clean up is to delete the project entirely.

1. In the Google Cloud Console, select the project you created.
2. Click DELETE.

Alternatively, if you want to keep the project but delete resources:

1. Delete Firestore Database: Go to Firebase Console > Firestore and delete the database.
2. Delete Authentication: Go to Firebase Console > AuthenticationSign-in method, disable Google.

7. Congratulations

Congratulations! You have successfully used the Gemini CLI Conductor extension to build a web application from scratch and then iterate on it with complex features like authentication and database integration.

Next steps

• Explore Gemini CLI Plan Mode for light-weight planning
• Explore more Gemini CLI Extensions