Getting Started with Conductor for Gemini CLI

--> Getting Started with Conductor for Gemini CLI - KDnuggets

-->

Join Newsletter

Introduction

When you open Gemini CLI, describe a feature you need to build, and the agent immediately starts writing code. No questions, no clarifications, no plan. Ten minutes later, you have a hundred lines of implementation across four files and none of it matches your actual architecture because the agent never knew your architecture. It made plausible guesses. Some were right. Most weren't. Now you're untangling AI-generated code while wondering if it would have been faster to just write it yourself.

That's not a Gemini problem. That's a context problem. The agent doesn't know what you're building, what libraries you've chosen, what your coding standards are, or what the feature is actually supposed to do. Every session starts from zero.

Conductor, released in preview on December 17, 2025, is a Gemini CLI extension built to fix this. It introduces a workflow called Context-Driven Development (CDD), a structured approach where your project context, specs, and implementation plans live in Markdown files inside your repository, not inside an ephemeral chat window. The agent reads those files every time it touches your project. Your style guides, your tech stack decisions, your product goals — all of it persists and travels with the code.

Since launch, the Conductor GitHub repository has accumulated over 3,600 stars and 284 forks. A Google Codelab walking through a full greenfield project with Conductor went live in April 2026. This article covers everything you need to go from zero to running your first implementation track.

What Conductor Actually Is

Before getting into the commands, it helps to understand the model Conductor is built on, because it changes how you think about AI-assisted development.

Standard AI coding workflows are stateless. You open a session, describe what you want, the agent works, you close the session. Next time you open it, the agent remembers nothing about what you built, why you built it, or what comes next. As one Google Cloud developer put it, the model is "transient, forgetful, and a bit of a cowboy."

Conductor solves this by making context a managed artifact. Instead of describing your project fresh every session, you maintain a set of Markdown files that do that job permanently. The agent reads them on every run. Your coding standards are always loaded. Your product goals are always in scope. The feature plan is always visible.

Google's announcement post invokes Benjamin Franklin's "failing to plan is planning to fail" to describe the philosophy, and the framing holds. The Conductor workflow is: build context first, spec the feature, plan the implementation, then write code. In that order, every time.

Architecturally, Conductor operates as three layers working together.

The Command Layer is what you interact with — six slash commands inside Gemini CLI

The Artifact Layer is a conductor/ directory in your repo containing Markdown and JSON files that hold project state

The Version Control Layer is Git, which Conductor uses to create per-task commits and support its rollback functionality

This works for both greenfield projects (starting from scratch) and brownfield projects (existing codebases). The brownfield support is worth highlighting because most tutorials only demo clean-slate projects. When you run /conductor:setup on an existing repo, Conductor analyzes your codebase, respects your .gitignore and .geminiignore patterns, and infers your tech stack and architecture — so you're not manually filling in context Conductor can figure out itself.

Prerequisites and Installation

You need three things before installing Conductor.

Gemini CLI must be installed and working. Install it globally with npm:

Install Gemini CLI globally

npm install -g @google/gemini-cli

Verify installation

gemini --version

If you run into permission errors, use a Node version manager like nvm rather than running as root. After installing, restart your terminal so the gemini binary is in your PATH.

A Google API key or Vertex AI setup is required for Gemini CLI authentication. When you first run gemini, it will prompt you to authenticate. Select Vertex AI and follow the guide to set your GOOGLE_API_KEY environment variable, or complete the browser-based OAuth flow for personal use.

Git must be initialized in your project directory. Conductor creates per-task commits and relies on Git for its revert functionality. If you're starting a new project:

Initialize a new git repository if you haven't already

mkdir my-project && cd my-project git init git commit --allow-empty -m "Initial commit"

With those in place, install Conductor:

Install the Conductor extension

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

The --auto-update flag keeps Conductor updated to new releases automatically.

Recommended for most users.

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

The installation downloads the extension from the GitHub repository, registers the six Conductor commands, configures a GEMINI.md context file as the entry point, and sets /conductor as the plan directory. The whole process takes a few seconds.

Verify it worked by launching Gemini CLI and typing /conductor:

gemini

Then inside the Gemini CLI session:

/conductor

You should see the full list of sub-commands: setup, newTrack, implement, status, revert, and review. If you see those, you're ready.

Setting Up Your Project with /conductor:setup

Run this once per project. It's the command that builds the foundation everything else depends on. Inside your Gemini CLI session, from your project directory:

/conductor:setup

Conductor will immediately start analyzing your project. For a brownfield project, it scans your codebase to infer what it's working with — respecting .gitignore to avoid token-heavy directories like node_modules or pycache. For a new project, it asks you to describe what you're building.

Either way, it then walks you through a guided Q&A to populate six artifacts it creates inside a new conductor/ directory:

conductor/ ├── product.md # Product vision, users, goals, key features, success criteria ├── product-guidelines.md # UI standards, voice and tone, error handling behavior ├── tech-stack.md # Languages, frameworks, databases, infrastructure ├── workflow.md # TDD preferences, commit strategy, verification protocol ├── code_styleguides/ # Language-specific style guides (auto-generated per language found) │ ├── python.md │ ├── typescript.md │ └── ... └── tracks.md # Master registry of all tracks (starts empty)

Each artifact plays a specific role. product.md answers the "what are we building and for whom" question. tech-stack.md ensures the agent never suggests a library or pattern outside your stack. workflow.md is where you define whether you want test-driven development (TDD), what your commit strategy looks like, and what manual verification steps you require before phases proceed. code_styleguides/ contains per-language guides that Conductor ships with pre-populated templates for, which you can then customize.

Once setup completes, you'll see the conductor/ directory in your project. Commit it:

Commit the conductor context to your repo

git add conductor/ git commit -m "chore: initialize Conductor context-driven development"

From this point on, any teammate who clones the repo and opens Gemini CLI has the full project context available immediately — no onboarding conversation needed.

Starting a Feature with /conductor:newTrack

A track is how Conductor represents a unit of work. One feature, one bug fix, one architectural change — one track. Tracks give the agent a defined scope to work within, which is the core mechanism that prevents it from wandering.

Start a track by describing what you want to build:

/conductor:newTrack "Add a dark mode toggle to the settings page, persisting the preference to localStorage"

You can also call /conductor:newTrack without an argument and describe the feature interactively when Conductor prompts you.

Conductor takes your description, reads the full project context from conductor/, and generates three files inside a new conductor/tracks// directory:

conductor/tracks/ └── dark_mode_20260614/ ├── spec.md # The "what and why" -- requirements, goals, technical constraints, out of scope ├── plan.md # The phased, task-level implementation checklist └── metadata.json # Track ID, creation date, current status

The track ID format is shortname_YYYYMMDD, so dark_mode_20260614 for a dark mode track created on June 14, 2026. This keeps tracks sorted chronologically in your file system.

spec.md contains the specification: what problem this solves, what the goals are, the technical requirements, and explicitly what is out of scope. The out-of-scope section matters more than it looks — it prevents the agent from gold-plating a feature when it should be shipping it.

plan.md is the implementation checklist, organized into phases. A dark mode feature might look like this:

Implementation Plan - Dark Mode Toggle

Phase 1: Foundation

• [ ] Task: Add theme key to the localStorage schema and document it in the project README
• [ ] Task: Create a useTheme hook that reads/writes the theme value and defaults to system preference
• [ ] Task: Write unit tests for useTheme -- verify default behavior, localStorage read, localStorage write
• [ ] Task: Conductor - User Manual Verification 'Foundation' (Protocol in workflow.md)

Phase 2: UI Component

• [ ] Task: Build ThemeToggle component with accessible toggle button (aria-label, keyboard support)
• [ ] Task: Apply conditional CSS classes based on the current theme value from useTheme
• [ ] Task: Write component tests for ThemeToggle -- renders correctly, fires toggle on click
• [ ] Task: Conductor - User Manual Verification 'UI Component' (Protocol in workflow.md)

Phase 3: Settings Page Integration

• [ ] Task: Import ThemeToggle into the Settings page component
• [ ] Task: Verify that preference persists across page refreshes and new browser tabs
• [ ] Task: Write integration test for the full settings page with dark mode enabled
• [ ] Task: Conductor - User Manual Verification 'Settings Page Integration' (Protocol in workflow.md)

Read this plan before you run /conductor:implement. This is the human-in-the-loop moment Conductor is designed around. If the phases are wrong, if a task is missing, or if the scope is wider than you intended, edit plan.md now. Once you run implement, Conductor commits code against this plan. Changing course mid-implementation is possible but more expensive than catching it here.

Implementing with /conductor:implement

Once you're satisfied with the plan:

/conductor:implement

This is where Conductor earns its place. It reads plan.md, picks up the first unchecked task, and starts working through the list. As it starts a task, it updates the checkbox from [ ] to [~] (in progress). When it completes the task, it updates it to [x] and creates a Git commit — one commit per completed task. Not per phase, not per session, per task.

You'll see commits accumulating as Conductor works:

git log --oneline

Output example:

a3f9c12 feat(theme): write integration test for settings page dark mode b7e2d45 feat(theme): import ThemeToggle into Settings page c1a8f90 feat(theme): add accessible toggle button with aria-label d4b3e21 feat(theme): create ThemeToggle component with conditional CSS e5c6d78 test(theme): write unit tests for useTheme hook f7d9a34 feat(theme): create useTheme hook with localStorage persistence

At the end of each phase, Conductor pauses for manual verification. You don't proceed to the next phase until you confirm the cu

[truncated for AI cost control]