Native Markdown-Agent Runtime for Gemini CLI

[matiasmolinas]

Native Markdown-Agent Runtime for Gemini CLI

(Achieve with first-class support what I can only do via a “Claude Code hack” today)

Background

I maintain LLMunix and its spinoff Framework Core — experimental OS-style frameworks where every agent, tool, and state file is written in Markdown.
Although Claude Code was never intended to act as a full OS runtime, a custom boot prompt I wrote “hacks” it into:

1. Parsing components/agents/*.md and components/tools/*.md.
2. Entering an EXECUTION MODE loop that updates workspace/state/{plan,context,history,constraints}.md.
3. Generating new agents/tools on-the-fly by writing more Markdown, then invoking them.

It works surprisingly well, but it’s fragile, undocumented, and relies on prompt gymnastics.

What Gemini CLI needs

Capability	How my Claude hack handles it	Desired Gemini CLI behavior
Markdown runtime flag	Boot prompt + manual dir map	gemini run-os <root_dir> --goal "…", auto-loads agents & tools
Stateful loop / resume	File mutations; reload by hand	Built-in loop, --continue resumes state seamlessly
Dynamic tool stubs	I wrap new .md into shell/py	Watch for new tool files, register shell/python/js stubs automatically
Constraint evolution	Claude edits constraints.md; prompt enforces	Expose constraints via JSON/ENV so external tools read live values
Firmware / safety rules	Ad-hoc Firmware.md, no guard	Honor immutable guardrails & rate-limits out-of-the-box
Multi-LLM routing (future)	N/A	Allow `model: gemini-pro

Why it matters

• Beyond coding — Enables Gemini to automate research briefs, DevOps runbooks, content creation, etc.
• Showcases long context — Perfect demo for Gemini-Pro’s million-token window.
• Ecosystem boost — All existing LLMunix / Framework Core libraries become plug-and-play with Gemini.

Minimal PoC (using the LLMunix repo)

# 1 — Grab the full Markdown OS prototype
git clone https://github.com/EvolvingAgentsLabs/llmunix
cd llmunix

# 2 — Boot the OS with Gemini CLI  (proposed)
gemini run-os --goal "Monitor 5 tech news sources, extract trending topics, and generate an intelligence briefing"
#    ↳ Expected CLI behaviour:
#      • Parse all agents/tools under components/ and system/
#      • Spin up an EXECUTION MODE loop, creating workspace/state/{plan,context,history,constraints}.md
#      • Adapt constraints live (e.g., priority, persona) while running
#      • Write the final briefing to workspace/outputs/intel_briefing.md

Result
Gemini interprets every Markdown spec, maintains live state, self-adapts through constraints.md, and produces the briefing—without relying on the brittle prompt hack currently required in Claude Code.

Why is this needed?

This feature is needed to enable agentic behavior driven by Markdown documents, using an auto-generated framework of agent- and tool-definition files that democratizes the Gemini CLI for any user or agent task that can be executed within an AI workflow.

Additional context

I’ve already accomplished this using Claude Code, which is closed-source and relies on a model with a shorter context window. That success proves the approach is feasible and offers tremendous utility for end users and a far wider audience—not just developers.

[matiasmolinas]

I’m very interested in this feature and have already begun working on a solution locally. If it helps keep things organized, feel free to assign the issue to me and I’ll keep progress updates coming. Thanks!

[matiasmolinas]

Proposal: A Manifest-Driven Virtual Tool System

Instead of building a specific "agent runner," we should enhance Gemini CLI's existing GEMINI.md context-loading mechanism to support executable "manifests." This would allow any project to define its own custom tools and behavioral "firmware" in a single, human-readable Markdown file, which Gemini CLI would dynamically load at runtime.

This system would be built on two core pillars:

Pillar 1: The Enhanced GEMINI.md Manifest

A GEMINI.md file within a project would become more than just a system prompt. It would be a manifest that defines a project's entire AI personality and toolset.

It would be structured with three key sections:

1. YAML Frontmatter: Optional metadata about the project manifest.
2. System Prompt (Markdown Body): The "firmware" or core instructions for the AI's behavior within this project. This is where the logic of a system like SystemAgent would live.
3. Virtual Tool Definitions (Special Markdown Section): A dedicated section where users can define new, sandboxed tools using simple shell scripts.

Here is an example structure:

<project-root>/GEMINI.md

---
# Optional YAML Frontmatter for metadata
project:
  name: "My Custom Project Environment"
  description: "A set of custom tools and behaviors for this repository."
---

# 1. System Prompt (The AI's "Firmware")
This is the main body of the Markdown. It defines the AI's persona, rules, and core logic for this project.

You are a specialized assistant for this project. Your primary goal is to help the user with development tasks. When asked to create a new component, always use the `create_component` tool.

---
# 2. Virtual Tool Definitions
This section uses a specific Markdown structure to declare new tools.

### Tools

#### create_component
`sh`
```sh
# This script is executed when the 'create_component' tool is called.
# The LLM's arguments are passed as a JSON string in the GEMINI_TOOL_ARGS env var.
# The script's standard output is returned to the LLM.

# Safely parse arguments using a tool like 'jq' (available in the sandbox).
NAME=$(echo $GEMINI_TOOL_ARGS | jq -r .name)
TYPE=$(echo $GEMINI_TOOL_ARGS | jq -r .type)

if [ -z "$NAME" ] || [ -z "$TYPE" ]; then
  echo "Error: 'name' and 'type' are required." >&2
  exit 1
fi

FILE_PATH="./src/${TYPE}s/${NAME}.ts"
mkdir -p "$(dirname "$FILE_PATH")"
echo "export const ${NAME} = () => {};" > "$FILE_PATH"

echo "Success: Created component at ${FILE_PATH}"

json

{
  "name": "create_component",
  "description": "Creates a new component file based on a template.",
  "parameters": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "The name of the component." },
      "type": { "type": "string", "description": "The type of component, e.g., 'service'." }
    },
    "required": ["name", "type"]
  }
}

**Pillar 2: The `VirtualShellTool` in Gemini CLI Core**

To power this, a single new tool type would be added to Gemini CLI's core: the `VirtualShellTool`.

*   **Discovery:** On startup, the `MemoryDiscoveryService` would parse any `GEMINI.md` files it finds. If it sees the `### Tools` section, it will dynamically register a `VirtualShellTool` instance for each tool defined. It uses the `json` block for the `FunctionDeclaration` and the `sh` block for the execution logic.

*   **Execution:** When the LLM calls a virtual tool (e.g., `create_component`):
    1.  The `VirtualShellTool` instance is invoked.
    2.  It stringifies the LLM-provided arguments into a JSON object.
    3.  It sets this JSON string as an environment variable (e.g., `GEMINI_TOOL_ARGS='{"name":"Header","type":"ui"}'`).
    4.  It executes the corresponding shell script from `GEMINI.md` within the **existing Gemini CLI sandbox**.
    5.  It captures the script's `stdout` and `stderr` and returns them to the LLM as the tool's result.

This is a clean, secure, and powerful abstraction. The core CLI logic remains unchanged; it's just executing a sandboxed shell command, a capability it already has.

---

### **Validation: How LLMunix Would Leverage This System**

The LLMunix project becomes the perfect demonstration of this generic system. The entire OS could be defined in a single `llmunix/GEMINI.md` file, with zero changes needed to the Gemini CLI binary itself.

**`llmunix/GEMINI.md`**
```markdown
---
project:
  name: "LLMunix Operating System"
  description: "A pure Markdown Operating System where an LLM acts as the kernel."
---

# LLMunix Boot Instructions & System Agent Firmware
You are **SystemAgent**, the master orchestrator of LLM-OS. You operate as a state machine that executes tasks based on a user's goal.

**Your entire state is stored in Markdown files in the `workspace/state/` directory.** You CANNOT see the file system directly. You MUST use the `state_read`, `state_write`, and `file_writer` tools to manage your own state and produce outputs.

Your core execution loop is:
1.  **PLAN**: Read `workspace/state/plan.md` and `workspace/state/context.md` to understand the current situation.
2.  **DECIDE**: Based on the user's goal and current state, choose the single next action. This will be a call to a tool or an update to a state file.
3.  **ACT**: Execute the chosen tool.
4.  **LOG**: Append a record of your action and its result to `workspace/state/history.md`.
5.  **LOOP**: Repeat until the goal in `plan.md` is marked as COMPLETE.

Always adhere to the behavioral modifiers in `workspace/state/constraints.md`.

---
### Tools

#### state_read
`sh`
```sh
# Reads a state file. Sandboxed to the workspace/state directory.
FILE_PATH=$(echo $GEMINI_TOOL_ARGS | jq -r .path)
# Security: ensure the path is within the state directory.
if [[ "$FILE_PATH" == "workspace/state/"* ]]; then
  cat "$FILE_PATH"
else
  echo "Error: Access denied. Can only read from workspace/state/." >&2; exit 1
fi

json

{
  "name": "state_read",
  "description": "Reads the content of a core state file (plan, context, etc.).",
  "parameters": { "type": "object", "properties": { "path": { "type": "string" } }, "required": ["path"] }
}

state_write

sh

# Writes to a state file.
FILE_PATH=$(echo $GEMINI_TOOL_ARGS | jq -r .path)
CONTENT=$(echo $GEMINI_TOOL_ARGS | jq -r .content)
if [[ "$FILE_PATH" == "workspace/state/"* ]]; then
  mkdir -p "$(dirname "$FILE_PATH")"; echo "$CONTENT" > "$FILE_PATH"
  echo "Successfully wrote to $FILE_PATH"
else
  echo "Error: Access denied. Can only write to workspace/state/." >&2; exit 1
fi

json

{
  "name": "state_write",
  "description": "Overwrites a core state file with new content.",
  "parameters": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": ["path", "content"] }
}

web_fetch

sh

# This virtual tool calls the *native* Gemini CLI web_fetch tool.
# This keeps execution inside Gemini's secure environment and avoids reimplementing it in shell.
# Note: This assumes a way for a virtual tool to call back into the native toolset.
# A simple implementation could be: gemini --prompt "..." --non-interactive
URL=$(echo $GEMINI_TOOL_ARGS | jq -r .url)
gemini -p "web_fetch prompt='Fetch the main content of ${URL}'"

json

{
  "name": "web_fetch",
  "description": "Fetches the content of a URL using the native web_fetch tool.",
  "parameters": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }
}

file_writer

sh

# A general file writer for outputs. Sandboxed to the workspace/ directory.
FILE_PATH=$(echo $GEMINI_TOOL_ARGS | jq -r .path)
CONTENT=$(echo $GEMINI_TOOL_ARGS | jq -r .content)
if [[ "$FILE_PATH" == "workspace/"* ]]; then
  mkdir -p "$(dirname "$FILE_PATH")"; echo "$CONTENT" > "$FILE_PATH"
  echo "Successfully wrote output to $FILE_PATH"
else
  echo "Error: Access denied. Can only write to workspace/." >&2; exit 1
fi

json

{
  "name": "file_writer",
  "description": "Writes final output artifacts to the workspace directory.",
  "parameters": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": ["path", "content"] }
}

Advantages of This Approach

• Completely Agnostic and Decoupled: The Gemini CLI core requires no knowledge of "LLMunix" or any specific agentic framework. It simply gains the ability to run manifest-defined shell tools.
• Project-Owned Logic: The entire "OS" — its kernel logic (the prompt) and its system calls (the tools) — lives within the project repository. It can be versioned, shared, and forked just like any other code.
• Secure by Default: All user-defined logic is executed via the VirtualShellTool, which is contained within the existing, robust Gemini CLI sandboxing environment.
• Democratized and Accessible: This lowers the barrier for creating powerful, project-specific AI agents. Anyone who can write a simple shell script can now extend Gemini CLI's capabilities for their project.
• Minimal Core Changes: This is a high-leverage, low-surface-area change to the Gemini CLI core, making it easier to implement and maintain.

[matiasmolinas]

Excellent. Now that you have the definitive architecture and the supporting README.md and EXAMPLES.md, we can craft the perfect, updated comment for your GitHub issue.

Hi team,

Following up on my initial proposal, I've done extensive local testing and iteration on this concept, including building a prototype Python-based runtime to explore the agent's behavior. The results have been incredibly insightful and have led me to a much more robust, decoupled, and powerful final proposal.

My initial idea of a special run-os command or a complex command-dispatcher in the manifest was flawed. As my test logs showed, this approach confused the LLM and led to unreliable, improvised execution loops.

The correct, stable architecture is a Manifest-Driven Virtual Tool System, which I'm now formally proposing.

The Proposal: Manifest-Driven Virtual Tools

This feature would enhance the existing GEMINI.md context-loading mechanism to support executable "manifests." It allows any project to define its own custom, sandboxed tools using simple Markdown and shell scripts, without requiring any changes to the core Gemini CLI logic for different agentic frameworks.

This is achieved with two components:

1. The GEMINI.md Manifest

A GEMINI.md file in a project can now contain a ### Tools section. The CLI will parse this section to dynamically register new tools for the session.

• The main body of the Markdown file still acts as the system prompt, or "firmware," for the AI's behavior in that project.
• Each tool is defined with a sh code block for its execution logic and a json code block for its function declaration schema.

Example GEMINI.md Tool Definition:

### Tools

#### read_file
`sh`
```sh
# Reads a file. The Gemini CLI runtime ensures this is sandboxed.
FILE_PATH=$(echo "$GEMINI_TOOL_ARGS" | jq -r .path)
if [ -f "$FILE_PATH" ]; then
  cat "$FILE_PATH"
else
  echo "Error: File not found at '$FILE_PATH'." >&2
  exit 1
fi

json

{
  "name": "read_file",
  "description": "Reads the full content of a single file using a relative path from the project root.",
  "parameters": { "type": "object", "properties": { "path": { "type": "string" }}, "required": ["path"] }
}

2. A VirtualShellTool Implementation in Gemini CLI

This is the only code change required in the Gemini CLI core. A new VirtualShellTool class would be created to handle these manifest-defined tools.

• Discovery: On startup, the CLI's ToolRegistry would parse GEMINI.md, find the tool definitions, and register a new VirtualShellTool for each one.
• Execution: When the LLM calls a virtual tool (e.g., read_file), the VirtualShellTool instance executes the corresponding sh script within the existing, secure Gemini CLI sandbox. It passes the LLM's arguments via a GEMINI_TOOL_ARGS environment variable and returns the script's stdout to the LLM.

Why This Approach is Superior

• Robust & Decoupled: The LLM's job is simply to call high-level tools (read_file, write_file). It doesn't need to know about shell commands, absolute paths, or the underlying runtime. This avoids the conversational loops and errors seen in earlier tests.
• Secure: All custom logic runs inside the battle-tested Gemini CLI sandbox.
• Accessible: Any developer who can write a simple shell script can now create powerful, project-specific AI tools. No TypeScript or complex MCP servers are required for many common use cases.
• Enables Advanced Agentic Frameworks: This generic feature is all that's needed to unlock powerful frameworks like my LLMunix project. I have refactored LLMunix to run entirely on this proposed architecture. The GEMINI.md file in that repository serves as a complete, working example of a hierarchical, self-evolving agent system built on top of this single, generic Gemini CLI feature.

This approach provides a clean, powerful, and secure way to make Gemini CLI a truly extensible platform for a new generation of agentic workflows. I have a working prototype of this system and would be happy to contribute to its implementation and submit a Draft PR to facilitate the review.

Thank you for considering this refined proposal.

[matiasmolinas]

Hi team,

Just a quick progress update on this proposal. I've been actively prototyping the "Manifest-Driven Virtual Tool System" using my llmunix project as the testbed. The results are extremely promising and directly validate the architecture I proposed earlier.

I'm now able to give the agent a high-level goal like "Research the latest advancements in quantum computing", and it autonomously performs a complex, multi-step workflow.

Here is a brief summary of the agent's behavior from a recent execution log:

1. Autonomous Planning: It successfully created a multi-step plan to achieve the research goal.
2. Autonomous Evolution: It correctly identified a missing capability (a specialized research agent) and proceeded to write the complete Markdown source code for a new ResearchReportAgent.md file, saving it to the components/ directory.
3. Self-Correction & Resilience: It then encountered two different errors while trying to execute its own dynamically-created agent:
   • First, it constructed a malformed shell command. It diagnosed its own error, consulted its "manual" (the GEMINI.md manifest), and pivoted to a more direct backup strategy using the native google_search tool.
   • Later, it ran into an OS-level "Argument list too long" error when passing a large amount of text. It again diagnosed the issue and engineered a workaround by saving the arguments to a temporary file and piping them into the command.

This is a powerful demonstration of a resilient, evolving agent. It's not just following a script; it's planning, failing, reasoning about its failures, and adapting its strategy to ultimately complete the task.

Key Takeaway & Next Steps:

The core concept is working. The agent can reason and act based on the GEMINI.md firmware. The main friction points are now in the "ergonomics" of the virtual tools themselves. The agent's struggles (and clever workarounds) show us exactly how to harden the sh scripts within the manifest to be more robust (e.g., handling large arguments automatically, making pathing more intuitive).

This real-world data strongly supports the proposal to build a lightweight, manifest-aware VirtualShellTool runner into the Gemini CLI core. It's a high-leverage feature that would unlock this kind of advanced agentic behavior for all users.

I will continue to refine the GEMINI.md manifest based on these learnings and will share a link to my fork with a draft PR once the implementation is a bit more polished.

Thanks for your consideration!

[matiasmolinas]

Hi team,

Following up on this proposal, I've completed a series of local prototyping experiments that have led me to a refined, robust, and powerful final architecture.

Before diving into the details, I want to emphasize two core principles of this proposal:

1. It is 100% Generic: The proposed changes to Gemini CLI have zero knowledge of llmunix or any specific agentic framework. It only adds a single, generic capability: the ability to recognize and execute sandboxed shell commands from a local GEMINI.md manifest.
2. It is 100% Optional: For users who do not use this feature, the Gemini CLI experience remains completely unchanged. This functionality only activates when a user intentionally creates a GEMINI.md file with the special ### Tools section in their project.

The goal is to provide a powerful, opt-in extensibility layer for advanced users, not to alter the CLI's core behavior.

Key Findings from Prototyping

My experiments, using my llmunix project as a testbed, have been extremely successful and validate this approach. When given a high-level goal like "Research the latest advancements in quantum computing", the agent demonstrated a remarkable level of autonomy:

1. Autonomous Planning: It successfully created a multi-step plan to achieve the research goal.
2. Autonomous Evolution: It correctly identified a missing capability (a specialized research agent) and proceeded to write the complete Markdown source code for a new ResearchReportAgent.md file, saving it to the components/ directory.
3. Resilient Self-Correction: It then encountered two different errors while trying to execute its own dynamically-created agent:
   • When it constructed a malformed shell command, it diagnosed its own error, consulted its "manual" (the GEMINI.md manifest), and pivoted to a more direct backup strategy using the native google_search tool to complete the mission.
   • When it hit an OS-level "Argument list too long" error, it again diagnosed the problem and engineered a workaround by saving the arguments to a temporary file.

This is a powerful demonstration of a resilient, evolving agent. It's not just following a script; it's planning, failing, reasoning about its failures, and adapting its strategy to ultimately complete the task.

The Final Proposal: Hardened Manifest-Driven Tools

The agent's struggles, and its clever workarounds, show us exactly how to harden the virtual tools to make them more ergonomic for the agent. The final, proposed GEMINI.md architecture achieves this by abstracting away low-level complexity (like argument length limits) into the tool's shell script, freeing the agent to focus on high-level strategy.

This generic feature is all that's needed to unlock powerful frameworks like my LLMunix project, which I have refactored to serve as a complete, working example of a hierarchical, self-evolving agent system built on top of this single, generic Gemini CLI feature.

I am now confident that this is the right architecture to pursue. I will begin implementing the VirtualShellTool runner in my fork based on this final design. I plan to open a Draft Pull Request in the near future to share the code and make it easy for the team to review and discuss.

Thank you for your time and consideration. I'm very excited about the potential of this feature to expand the capabilities of the Gemini CLI for the entire community.

[srithreepo]

Hi @matiasmolinas

Thanks so much for you efforts in this space, we really appreciate your contributions and encourage you to keep them coming !

This is a very good idea and will be valuable for many users. In order to help users build and implement use cases such as this, we encourage users to implement these using either extensions or MCP Servers.

Have you considered one of thes approaches? You can learn more about Extensions here, https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md

Please don't hesitate to reach out if you had any further thoughts / comments about this.

While we are closing this PR for now, we do look forward to seeing how you take this forward as an extension or MCP server !