Claude-Gemini Compatibility

Research and tools addressing compatibility between Claude Code's claude.md '@' processing and Gemini CLI implementation.

Objective

Elevate the CLAUDE.md '@' compatibility issue from low priority by providing evidence-based research that documents differences, demonstrates impact, and builds community consensus.

Structure

• docs/at-file-inclusion-specification.md - '@' file inclusion syntax specification
• docs/claude-compatibility/ - summary and action plan
• scripts/find-claude-md-examples.cjs - GitHub search for real-world examples
• scripts/commit-msg, scripts/rewrite_msg.sh - conventional-commit hook and history rewrite tool
• integration-tests/claude-compatibility.test.js - Compatibility test suite
• .github/workflows/ci.yml - CI (node 18.x/20.x)
• workspace/ - my work with Google Gemini CLI (24 issues/PRs, with data)
• site/ - portfolio site (deployed to GitHub Pages via .github/workflows/pages.yml)

My work with Google Gemini CLI

Rendered workspace: workspace/ with 24 issues/PRs by or mentioning @bniladridas (3 merged: #2230, #2978, #13374). Public site builds from the same data on every push to main (see Pages deployment).

Core Differences

File Boundaries

• Claude: --- File: /path/to/file.md ---
• Gemini: <!-- Imported from: ./file.md -->

Processing

• Claude: Flat concatenation with deduplication
• Gemini: Hierarchical with in-place replacement

Structure

• Claude: No hierarchy presentation
• Gemini: Tree format preserves hierarchy

Impact

LLM Processing

• Inconsistent file boundary recognition
• Variable content ordering affects context
• Different debugging approaches

Migration Challenges

• Existing CLAUDE.md files incompatible with Gemini CLI
• Manual conversion required
• Potential content structure issues

Implementation Path

Priority Elevation

1. Specification document ✓ (docs/at-file-inclusion-specification.md)
2. Real-world examples ✓ (docs/claude-compatibility/REAL-WORLD-EXAMPLES.md, 7 files / 14 imports)
3. Impact demonstration ✓ (test suite asserts flat-vs-tree deltas)
4. Community engagement (next; draft ready: docs/claude-compatibility/FORUM-DRAFT.md)

Technical Solution

• Use upstream importFormat: 'flat' for Claude-style processing (already merged in google-gemini/gemini-cli#2978)
• Document tree vs flat modes and when to use each
• Standardized file boundary markers
• Migration tools for existing files

Usage

Prerequisites: node >=18.

GitHub Search (set GITHUB_TOKEN to avoid rate limits)

GITHUB_TOKEN=ghp_... npm run search

cd scripts && node find-claude-md-examples.cjs

or

npm run search

Compatibility Tests

cd integration-tests && node claude-compatibility.test.js

or

npm run test

Specification Review See docs/at-file-inclusion-specification.md for detailed syntax analysis.

Conventional Commits This project follows conventional commit standards. To enable commit message validation:

# Copy the commit-msg hook to enable validation (then make executable)
cp scripts/commit-msg .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

# Preview rewrites first (safe dry-run):
./scripts/rewrite_msg.sh
# Only when clean + backed up, apply:
./scripts/rewrite_msg.sh --apply

Commit messages must:

• Start with types: feat:, fix:, docs:, style:, refactor:, test:, chore:, perf:, ci:, build:, revert:
• Have lowercase message body
• Be ≤60 characters for the first line

Next Steps

1. Post docs/claude-compatibility/FORUM-DRAFT.md to gemini-cli discussions and link replies back here
2. Re-run GITHUB_TOKEN=... npm run search to replace curated examples with live API results
3. Develop migration guide
4. Propose implementation changes (document flat as recommended for CLAUDE.md-origin files)

License

This work is released under CC0 1.0 Universal - dedicated to the public domain.

References

• Claude Code Memory
• Gemini CLI Memory Import Processor
• Gemini CLI Memory Import Processor Tests
• Memory Import Processor Docs
• Provide context with GEMINI.md
• Original PR Comment (low-priority rationale)
• Merged PR #2978