gemini-cli - 💡(How to fix) Fix Feature request: expose GEMINI_SYSTEM_MD path in --include-directories for relative reference resolution [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
google-gemini/gemini-cli#25215Fetched 2026-04-13 05:45:52
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
Participants
Timeline (top)
labeled ×2cross-referenced ×1

When using GEMINI_SYSTEM_MD to inject a custom system prompt from an external file, relative file references inside that markdown file are resolved from the current working directory, not from the directory containing the system prompt file.

Root Cause

When using GEMINI_SYSTEM_MD to inject a custom system prompt from an external file, relative file references inside that markdown file are resolved from the current working directory, not from the directory containing the system prompt file.

Fix Action

Fix / Workaround

Current workaround

Code Example

/path/to/agent/instructions/AGENTS.mdset as GEMINI_SYSTEM_MD
/path/to/agent/instructions/HEARTBEAT.md
/path/to/agent/instructions/TOOLS.md

---

See ./HEARTBEAT.md for execution checklist.
RAW_BUFFERClick to expand / collapse

Context

When using GEMINI_SYSTEM_MD to inject a custom system prompt from an external file, relative file references inside that markdown file are resolved from the current working directory, not from the directory containing the system prompt file.

Problem

If you have:

/path/to/agent/instructions/AGENTS.md   ← set as GEMINI_SYSTEM_MD
/path/to/agent/instructions/HEARTBEAT.md
/path/to/agent/instructions/TOOLS.md

And AGENTS.md contains:

See ./HEARTBEAT.md for execution checklist.

Gemini CLI resolves ./HEARTBEAT.md relative to the cwd (e.g. /workspace/project/) rather than relative to /path/to/agent/instructions/, making the reference fail silently.

Current workaround

Use --include-directories /path/to/agent/instructions/ alongside GEMINI_SYSTEM_MD. This works but requires the caller to know the directory separately from the env var.

Suggested fix

When GEMINI_SYSTEM_MD is set, automatically add dirname(GEMINI_SYSTEM_MD) to the list of directories used for relative file reference resolution — equivalent to how --include-directories works.

Alternatively, document that callers should always pair GEMINI_SYSTEM_MD with --include-directories $(dirname $GEMINI_SYSTEM_MD).

Background

This was discovered while building an agentic system (Paperclip) that uses Gemini CLI as a headless agent executor. We inject per-agent instruction files via GEMINI_SYSTEM_MD (system prompt level, analogous to Claude's --append-system-prompt-file). The instruction files cross-reference each other (AGENTS.mdHEARTBEAT.mdTOOLS.md) so relative resolution from the system prompt file's directory is essential.

extent analysis

TL;DR

To fix the issue with relative file references in custom system prompts, automatically add the directory of the GEMINI_SYSTEM_MD file to the list of directories used for relative file reference resolution.

Guidance

  • When setting GEMINI_SYSTEM_MD, consider using the --include-directories option with the directory of the GEMINI_SYSTEM_MD file to ensure relative file references are resolved correctly.
  • Verify that the directory of the GEMINI_SYSTEM_MD file is included in the list of directories used for relative file reference resolution to prevent silent failures.
  • To implement the suggested fix, modify the Gemini CLI to automatically add dirname(GEMINI_SYSTEM_MD) to the list of directories used for relative file reference resolution.
  • Document the requirement to pair GEMINI_SYSTEM_MD with --include-directories $(dirname $GEMINI_SYSTEM_MD) to ensure correct relative file reference resolution.

Example

GEMINI_SYSTEM_MD=/path/to/agent/instructions/AGENTS.md
--include-directories /path/to/agent/instructions/

Alternatively, the Gemini CLI could be modified to automatically include the directory of the GEMINI_SYSTEM_MD file:

GEMINI_SYSTEM_MD=/path/to/agent/instructions/AGENTS.md
# Automatically include /path/to/agent/instructions/ in the list of directories

Notes

The suggested fix assumes that the Gemini CLI has the capability to modify the list of directories used for relative file reference resolution. If this is not the case, an alternative solution may be required.

Recommendation

Apply workaround by using --include-directories with the directory of the GEMINI_SYSTEM_MD file, as this provides a reliable solution until the Gemini CLI is modified to automatically include the directory of the GEMINI_SYSTEM_MD file.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING