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.md → HEARTBEAT.md → TOOLS.md) so relative resolution from the system prompt file's directory is essential.
Context
When using
GEMINI_SYSTEM_MDto 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:
And
AGENTS.mdcontains:Gemini CLI resolves
./HEARTBEAT.mdrelative 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/alongsideGEMINI_SYSTEM_MD. This works but requires the caller to know the directory separately from the env var.Suggested fix
When
GEMINI_SYSTEM_MDis set, automatically adddirname(GEMINI_SYSTEM_MD)to the list of directories used for relative file reference resolution — equivalent to how--include-directoriesworks.Alternatively, document that callers should always pair
GEMINI_SYSTEM_MDwith--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.md→HEARTBEAT.md→TOOLS.md) so relative resolution from the system prompt file's directory is essential.