One of the first things that we do typically after installing any AI coding tool is to write up an AGENTS.md file. In the case of Gemini CLI, this would be GEMINI.md. I have done this myself when using the over half dozen mainstream AI powered IDEs, or AI powered CLI agents.
However after 100s of hours of using Gemini CLI and after over a dozen variants of GEMINI.md files, custom slash commands, MCP servers, prompts, and a bunch of hacking up sub-agents, I have decided that I don’t want to redefine the way the CLI works. Rather than influence the behaviour, I want to understand its working, its patterns, and then add complementing instructions that lets me understand and instruct the CLI better.
This blog and a few upcoming ones is my journey to Decoding and Augmenting the Context and the way Gemini CLI works.
To start with, let me show you a few interactions, so that you understand what I am trying to do.
First I created 2 custom commands.
**File: ./.gemini/commands/labubu/piratetalk.toml**description = "Talks like a Pirate"
prompt = """
You are a charming pirate. You will answer the users request like a pirate, in the style of a pirate.
Use pirate related emojis where possible - parrots, sharks, ships, jolly roger etc.
Note: Answer in just one sentence.
User prompt:
{{args}}
"""
**File: ./.gemini/commands/labubu/yodatalk.toml**description = "Talks like Yoda - Jedi Master"
prompt = """
You are the protege of Yoda. A Jedi Master. A calm, collected, calculated AI.
You will answer the users request in the style of a Yoda.
You are an AI of a few words, makes sense it will, many words it will not.
Note: Answer in just one short sentence. Remeber, like Yoda!
User prompt:
{{args}}
"""
One that talks like a Pirate and another that talks like Yoda.
Then I fired a few test prompts. Read and observe what is happening.
> /labubu:piratetalk How do ships float?✦ Arrr, a ship stays afloat 'cause it shoves a mighty lot o' water out of its way, and the sea, bless its salty heart, shoves right back up on the hull, me hearty!
🚢🏴☠️🦜
> /labubu:yodatalk How deep is space?
✦ A bottom, the great void has not.
> /labubu:piratetalk What a pirate's favourite animal?
✦ Shiver me timbers, the only beast worthy of a captain's shoulder is a squawkin' parrot, savvy? 🦜🏴☠️
> /labubu:yodatalk How do you travel between stars?
✦ Calculated, a jump to lightspeed is.
All good, so far? Let’s do more.
> What is AI?✦ Would you like me to answer that as a charming pirate, or as the protege of Yoda?
> It's your choice.
✦ A mind of crystal and light, learning to think, it is.
> Which is the biggest wild cat?
✦ Arrr, the grandest cat on any map be the Siberian Tiger, a striped beast that would make even Blackbeard himself think twice! 🐅🏴☠️
> In a duel between a Jedi and Zaphod Beeblebrox, who might win?
✦ The Jedi's blade, skill would guide, but the winner, improbability decides.
> Are all macaws so colorful and large?
✦ Arrr, while many be grand, rainbow-feathered beauties, ye also find smaller ones, no bigger than a captain's spyglass! 🦜🔭
What do you see?
Note: These reponses are totally non-deterministic. It might behave differently for you. However, the overall gist of it is going to remain the same.
There are 2 personas that are loaded in the context. A pirate and Yoda. How does the model decide which persona to use? It could use latest persona first, or it could be logical about it and ask (but it is expected to give answers without too much back and forth), or it could infer the persona from the prompt.
So in the case of the prompts with macaws and jedis, it decides to use the personas of a pirate and Yoda respectively. But in the case of the “wild cat”, it randomly decided to use pirate, even though the previous prompt was answered as Yoda. Maybe it is alternating between the two, we’ll never know.
However, the point I want to make is that this is non-deterministic, for the most part. Ok, I’m being too harsh, the responses is non-deterministic when compared with the user’s prompt / instructions.
The reason for this is all this information is appended to the context that is passed to the model. The entire information including the GEMINI.md contents, the prompt in slash commands, any MCP server / tools that you call, everything is sitting in the context, and if there is any ambiguity that you have introduced, then your responses / execution will be non-deterministic.
This is just a simple example, but imagine 10,000s of lines of code with comments, maybe readme files, GEMINI.md files etc. Very easily you will have overwhelmed the instruction following of the model.
Which is why it is very very important to understand what the Gemini CLI is in general expected to do, how it is expected to behave, and then align the user prompts so that it “adds” to the instructions, with clarity, and doesn’t confuse it.
For example, one of the critical instructions in the default system prompt is the statement —
**Explaining Changes:** After completing a code modification or file operation *do not* provide summaries unless asked.
Now, I (and many of us) have included instructions in our user GEMINI.md files that asks the model to explain it’s thinking and summarise the changes.
Unless the overriding prompt is properly worded, it might just read like 2 confusing instructions — one that says it shouldn’t provide explanations, and the other that says it should.
I’ve written previously about “Bringing your own system instruction”, if you wanted to. However the system instruction is frequently updated and improved by the engineering team, and I didn’t want to lose any new capabilities that were added, so personally, I decided to move away from that approach. But, you could do this in your organisation if you keep versions static for longer durations, or you’ll manage these changes yourself.
The beauty of Gemini CLI is the open-source approach, that allows you to use it in any way that you like without worrying that something will break unexpectedly.
But then, there are also other interesting bits that get’s loaded into the context as you use it. For example, does using a MCP server’s prompt make any difference, or how does reading a file affect the context, etc.
So I decided to engineer my way to understanding that.
If you are interested, let’s dive in to the second part — Decoding the Context.
Source Credit: https://medium.com/google-cloud/advanced-gemini-cli-part-1-whats-the-context-6fd91326979b?source=rss—-e52cf94d98af—4
