Gemini CLI

Make a project follow an instruction in Google's Gemini CLI: one command writes its hooks, and a new version arrives at your next prompt. The same setup for other tools, and how each one takes a new version, is on Other coding agents.

At a glance

How it followshooks
A new version arrivesat your next prompt
Set upone command
Checked againstGemini CLI v0.69.0, against its source
SystemsWherever the tool and Node.js 20.19 or later run

What you need: Node.js 20.19 or later, the instruction.md package (npm i -g instruction.md, 0.11.0 or later) and @instruction.md/agents 0.4.1 or later, which instruction agents … runs. Every instruction agents … command also runs, without installing anything, as npx -y @instruction.md/agents …, and every instruction … command as npx -y instruction.md ….

Set up

In your project's folder, signed in (instruction login), run:

Shell
instruction agents follow instruction://acme/support-agent@stable --host gemini-cli --write

It writes, merged into what is already there:

  • .instruction/follow.json: the instruction the project follows. Commit it.
  • .instruction/.gitignore: keeps the fetched copy (current.md), state.json and given/ out of git.
  • .gemini/settings.json: the hooks. Commit it.
.gemini/settings.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook gemini-cli",
            "timeout": 10000
          }
        ]
      }
    ],
    "BeforeAgent": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook gemini-cli",
            "timeout": 5000
          }
        ]
      }
    ],
    "PreCompress": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y @instruction.md/agents hook gemini-cli",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Gemini CLI asks you to trust a project's hooks, and again when a command changes (its timeouts are milliseconds).

What happens

A session gets the instruction's whole text when it starts (SessionStart). At each prompt (BeforeAgent) the hook adds nothing while the version is current, and the new version once one is released. Before Gemini CLI compacts a session (PreCompress), the hook forgets what the session holds, so the next prompt gets the whole text again.

Gemini CLI escapes < and > in what a hook adds, so the text arrives between plain marker lines (--- instruction … ---) instead of tags.

For your own instructions in every project, keep ~/.gemini/GEMINI.md current. Gemini CLI and Antigravity read it when a session starts:

Shell
instruction watch instruction://acme/support-agent@stable --out ~/.gemini/GEMINI.md --block

The MCP server

Gemini CLI speaks MCP 2025-06-18, so it reaches instruction.md through the instruction command's stdio server. instruction connect --host gemini-cli <uri> prints:

.gemini/settings.json
// .gemini/settings.json — Gemini CLI speaks MCP 2025-06-18, so it reaches instruction.md through this CLI's stdio server
{
  "mcpServers": {
    "instruction-md": {
      "command": "npx",
      "args": [
        "-y",
        "instruction.md",
        "mcp",
        "--follow",
        "instruction://acme/support-agent@stable",
        "--url",
        "https://instruction.md/mcp"
      ]
    }
  }
}
// sign the bridge in once: npx -y instruction.md login
// to give every session this instruction, and a new version at the next prompt: npx -y @instruction.md/agents connect --host gemini-cli instruction://acme/support-agent@stable --with-hooks --write
// for your own instructions in every project (read when a session starts): npx -y instruction.md watch instruction://acme/support-agent@stable --out ~/.gemini/GEMINI.md --block

Caveats and what isn't verified

  • What a hook adds reaches the model in the conversation, not in the system prompt.
  • Gemini CLI's hook timeouts are milliseconds: 10,000 at a session's start, 5,000 at a prompt.

Check it worked

Run the hook by hand, as the tool would at that event. It prints what the tool receives: the instruction's whole text the first time, and nothing when you run it again right away, because a session gets each version once.

Shell
echo '{}' | npx -y @instruction.md/agents hook gemini-cli --event SessionStart --dir .

Then start a new session and ask which instructions it follows. Once a session has read it, .instruction/current.md holds the copy the hooks keep, and the instruction's Agents card counts the follower under this tool.

Stop following

  • Remove the entries that run @instruction.md/agents hook gemini-cli from .gemini/settings.json.
  • Delete .instruction/follow.json, or the whole .instruction/ folder.

If it doesn't work

What you seeWhyWhat to do
Running the hook by hand prints nothingNo .instruction/follow.json in the folder or above it, up to the repository's root; or it gave this version moments agoRun the setup in the project's folder, or pass --dir. A version the session already has isn't given again: nothing is wrong
instruction.md: couldn't read …; this session goes on without itOffline, not signed in, or the address is wrong, and there is no copy yetinstruction login, then check the address in .instruction/follow.json
instruction.md: a newer version of … is held (…)The new version's signature doesn't check out, and the follow file asks for oneNothing to do on this machine: the session keeps the version it has. See How following works
A private instruction isn't readThe command isn't signed ininstruction login (--device on a machine without a browser)
Still stuckAsk us

Last checked against the product:

Was this page helpful? Report a problem