# Gemini CLI

> How midcode runs Google's Gemini CLI in the chat and in a terminal, what has to be installed and signed in first, and what to check when it won't start.

- Page: https://midcode.app/docs/agents/gemini-cli
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Gemini CLI runs in midcode's Agent panel in both views, with the account the CLI is signed in with on your Mac. midcode never handles your Google credentials: it starts the CLI in your project's folder and talks to it.

What the panel does for every agent (the prompt, the crosshair, permission cards, undo) is in [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## At a glance

| What | Chat | Terminal |
| --- | --- | --- |
| midcode starts | `gemini --acp` | `gemini`, typed into a login shell |
| Needs on your Mac | Gemini CLI, signed in | Gemini CLI, signed in |
| Account | Gemini CLI's own sign-in | Gemini CLI's own sign-in |
| Gemini's edits | Each one is a `⌘Z` step and a line in Publish | On the canvas and in Publish; undone with the CLI or git |

## Set it up

1. Install Gemini CLI, if you don't have it:

   ```bash
   npm install -g @google/gemini-cli
   ```

2. Run `gemini` once in a terminal and sign in.
3. In midcode, open the Agent panel and choose Gemini CLI in the "Agent" menu.

If the panel says "Gemini CLI isn't installed", it shows the same command with a button to copy it. Press "Check again" once it's installed.

## The chat

Gemini CLI speaks the Agent Client Protocol by itself, so there is no adapter in between and nothing extra is downloaded: midcode runs the `gemini` on your login shell's `PATH` with `--acp`, in your project's folder. If the CLI takes more than a few seconds to answer, the panel says "Getting Gemini CLI ready" while it waits.

The version is the one you installed. midcode doesn't update Gemini CLI, and what the chat can do follows it:

- The pickers under the prompt (mode, model, effort) are the options your Gemini CLI reports for the session. If it reports none, there are no pickers.
- Typing `/` at the start of the prompt lists the commands it reports.
- Images you attach go to Gemini as images when the CLI says it accepts them, and as file links otherwise.

Each edit Gemini makes is one `⌘Z` step and a line in [Publish](https://midcode.app/docs/publish/publish.md), named after it ("Gemini CLI: …"). The canvas shows the result at every breakpoint as your dev server reloads, so a layout that works on Desktop and breaks on Phone is in front of you while the agent is still working.

## The Terminal view

Switch the panel to the Terminal view ("Show as a terminal") and midcode opens a login shell in your project's folder and types `gemini`. It's the CLI as you know it. The two buttons in the header paste the selected element's reference, or your open comments, into its prompt.

In this view Gemini writes files by itself: they show on the canvas and in Publish's list of changed files, but they are not steps in midcode's `⌘Z`.

## Limits

- The chat's agent doesn't get the `GEMINI_…` variables your shell exports: they're left out when midcode starts it. If you use Gemini CLI with a `GEMINI_API_KEY` from your shell profile, the chat won't see that key. Use the Terminal view, which is your shell, or a sign-in the CLI keeps itself.
- midcode can't sign you in to Gemini CLI or switch its account. That's done in the CLI.

## Troubleshooting

**"Sign in to Gemini CLI first: run gemini once in a terminal."** The CLI started but has no sign-in it can use. Do that, then press "Try again".

**"Gemini CLI couldn't start".** The panel shows the reason it was given, often the last line the CLI printed. A Gemini CLI too old to know the `--acp` option is one cause: update it with the install command above.

**"Gemini CLI isn't installed", and it is.** Check that `gemini` runs in a new terminal window. midcode looks on your login shell's `PATH`; if installing it added a folder to your `PATH`, quit midcode and open it again.

To have Gemini write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).