feat: add Gemini CLI support via rtk init --gemini

[ousamabenyounes]

Summary

Introduce first-class support for Gemini CLI by adding a dedicated initialization mode that provides token optimization with the same ease-of-use as Claude Code integration.

---

Key Features

Core Implementation

• New flag: rtk init --global --gemini for one-command setup
• BeforeTool hook integration: Automatic command rewriting via ~/.gemini/settings.json
• Smart configuration: JSON-based hook registration compatible with Gemini CLI's event system
• Graceful uninstall: rtk init -g --uninstall removes all Gemini artifacts cleanly

Hook Mechanism

• Auto-rewrite: Intercepts run_shell_command tool calls before execution
• JSON I/O: Structured input/output format per Gemini CLI specification
• Command mappings: 20+ common commands (git, npm, docker, kubectl, file ops)
• Transparent operation: Gemini never sees the original command

User Experience

• Intelligent upsert: GEMINI.md updates preserve user content (via upsert_rtk_block)
• Status verification: rtk init --show displays Gemini configuration state
• Slim reference: ~/.gemini/RTK.md provides concise command documentation
• Easy validation: gemini /hooks confirms hook registration

---

Technical Details

Files Changed

src/init.rs                    +426 -21  (hook logic, settings.json patching)
scripts/test-gemini-init.sh    +91       (automated integration tests)
INSTALL.md                     +21 -1    (Gemini setup guide)
README.md                      +8 -3     (quick start updates)
src/main.rs                    +7 -1     (CLI flag addition)

Architecture Decisions

Separate hook implementation (REWRITE_GEMINI_HOOK):

• JSON-structured output (vs. Claude's text-based format)
• Event-driven architecture (BeforeTool matcher)
• Explicit settings.json registration (vs. auto-discovery)

Reused core logic:

• upsert_rtk_block(): Consistent update mechanism across AI tools
• ensure_hook_installed(): Parameterized for hook content injection
• uninstall(): Extended to handle both Claude and Gemini artifacts

Robust error handling:

• Settings.json creation if missing
• Hook deduplication (prevents multiple registrations)
• Graceful degradation on JSON parse failures

Testing Strategy

Comprehensive test coverage via scripts/test-gemini-init.sh:

1. Fresh installation: Verifies all files created with correct permissions
2. Upsert behavior: Confirms user content preservation during updates
3. Hook registration: Validates settings.json structure and hook presence
4. Clean uninstall: Ensures complete artifact removal

All tests use isolated $HOME to avoid pollution.

---

Usage Example

# Installation
rtk init -g --gemini

# Verification
gemini /hooks
# Expected output:
# BeforeTool hooks:
#   - rtk-rewrite (run_shell_command)

# Transparent usage
gemini "show me git status"
# → Hook rewrites to: rtk git status
# → Output: ~15 tokens (vs ~150 standard)

---

Documentation Updates

• INSTALL.md: Dedicated Gemini CLI Setup section with verification steps
• README.md: Quick Start updated with parallel Claude/Gemini instructions
• GEMINI.md: Auto-generated usage guide with command mappings and token savings

---

Compatibility

• Gemini CLI: v0.26.0+ (requires BeforeTool hooks support)
• RTK: All versions (backward compatible)
• Dependencies: Requires jq for JSON parsing in hook script

---

Migration Path

Existing Gemini users can adopt RTK with zero config changes:

rtk init -g --gemini  # One command, full setup
gemini /hooks         # Verify
# Start using Gemini normally - commands auto-optimized

---

Checklist

• Code follows project style guidelines
• Tests pass locally (cargo test)
• New tests added (scripts/test-gemini-init.sh)
• Documentation updated (INSTALL.md, README.md)
• No security concerns (reviewed with project security policy)
• Backward compatible (existing Claude Code users unaffected)

---

Author: Ousama Ben Younes ([@ousamabenyounes](https://github.com/ousamabenyounes))

Implementation Notes:
This PR was developed using AI-assisted coding with Gemini AI. The architecture, testing strategy, and integration design were manually crafted; code generation was AI-assisted and manually reviewed.

[bleleve]

To keep it understandable/simple in six months, I will have taken this approach:

• rtk init --claude
• rtk init --gemini
• rtk init --global -> auto CLIs detection (search for ~/.gemini and ~/.claude)

(By the way, Hey Ousama, I hope you are doing well 😄)

[bleleve]

There is a PR in progress similar to this one.
#158

[ousamabenyounes]

Hey! I’m doing great, hope you are too 🙂

I’m aligned with your approach and implementing it in a lightweight way.

There was #131, but it was considered too large and needed splitting.
So I decided to move forward with a lighter, more focused version instead.

I’ve also applied the requested fixes:
feat: auto-detect CLIs with rtk init --global, add --claude flag

I’m against duplicate work… just like I’m against copy-paste code 😄
Happy to align if #158 already covers it.

[ahundt]

hey just a heads up I've had one version of gemini support available for a bit here: #158