Gemini Workspace Bridge

Documentation Delegation

Documentation Source: For authoritative workspace patterns and current conventions, query gemini-cli-docs skill. This skill provides integration guidance; gemini-cli-docs provides official Gemini CLI documentation.

Overview

This skill defines the hybrid workspace architecture for Claude Code and Gemini CLI collaboration. It establishes conventions for file storage, artifact exchange, and cross-CLI communication.

When to Use This Skill

Keywords: workspace structure, artifact storage, cross-cli, shared files, gemini artifacts, claude artifacts, file locations, where to store

Use this skill when:

• Setting up a project for dual-CLI workflow

• Deciding where to store AI-generated artifacts

• Understanding the hybrid tracked/gitignored strategy

• Managing cross-CLI file exchange

Core Architecture

Hybrid Approach

The workspace uses a hybrid strategy:

• Tracked files: Memory files, valuable artifacts (plans, reports)

• Gitignored temp: Session state, caches, transient outputs

Directory Structure

project-root/ ├── CLAUDE.md # Source of truth (tracked) ├── GEMINI.md # Points to CLAUDE.md + overrides (tracked) │ ├── .claude/ │ ├── settings.json # Claude Code configuration │ └── temp/ # (gitignored) Session artifacts │ └── gemini-results/ # Parsed Gemini outputs │ ├── .gemini/ │ ├── settings.json # Gemini CLI configuration │ └── temp/ # (gitignored) Gemini session state │ └── docs/ # (tracked) Persistent AI artifacts └── ai-artifacts/ # Version-controlled reports ├── explorations/ # Codebase exploration reports └── plans/ # Implementation plans

Artifact Location Guide

Decision Tree

Is this artifact valuable long-term? ├── YES: Should others see it in git history? │ ├── YES → docs/ai-artifacts/ │ └── NO → .claude/temp/ or .gemini/temp/ └── NO: Is it session-specific? ├── YES → .claude/temp/ or .gemini/temp/ └── NO → Consider not storing it

Location Matrix

Artifact Type Location Tracked? Rationale

Memory/context CLAUDE.md , GEMINI.md

Yes Core project knowledge

Implementation plans docs/ai-artifacts/plans/

Yes Want to see evolution

Exploration reports docs/ai-artifacts/explorations/

Yes Reference material

Session results .claude/temp/gemini-results/

No Transient

Second opinions .claude/temp/gemini-results/

No Transient

Checkpoints ~/.gemini/history/<hash>/

No System-managed

Sync state .claude/temp/sync-state.json

No Internal tracking

Gitignore Recommendations

Add to project .gitignore :

AI session artifacts (transient)

.claude/temp/ .gemini/temp/

System-managed

.gemini/history/

Keep these tracked:

CLAUDE.md

GEMINI.md

docs/ai-artifacts/

File Naming Conventions

Timestamped Artifacts

Format: {type}-{scope}-{timestamp}.md

Exploration reports

exploration-architecture-2025-11-30T12-00-00Z.md exploration-dependencies-2025-11-30T14-30-00Z.md

Implementation plans

plan-add-auth-2025-11-30T12-00-00Z.md plan-refactor-db-2025-11-30T14-30-00Z.md

Session Results

Format: {operation}-{timestamp}.{json|md}

Raw Gemini results

query-2025-11-30T12-00-00Z.json analysis-2025-11-30T12-00-00Z.json

Processed results

analysis-summary-2025-11-30T12-00-00Z.md

Workspace Initialization

Initialize for Dual-CLI

Create directory structure

mkdir -p .claude/temp/gemini-results mkdir -p .gemini/temp mkdir -p docs/ai-artifacts/explorations mkdir -p docs/ai-artifacts/plans

Create GEMINI.md if not exists

if [ ! -f "GEMINI.md" ]; then cat > GEMINI.md << 'EOF'

GEMINI.md

@CLAUDE.md

Gemini-Specific Overrides

You are Gemini CLI. You have access to:

• Large context window (exceeds typical LLM limits)
• Interactive PTY shell (vim, git rebase -i)
• Checkpointing with instant rollback
• Policy engine for tool control

When working with this codebase, prioritize bulk analysis and exploration tasks that benefit from your large context. EOF fi

Update .gitignore

grep -q ".claude/temp/" .gitignore 2>/dev/null || echo ".claude/temp/" >> .gitignore grep -q ".gemini/temp/" .gitignore 2>/dev/null || echo ".gemini/temp/" >> .gitignore

Artifact Exchange Patterns

Pattern 1: Claude → Gemini (Context Handoff)

Claude prepares context

cat CLAUDE.md relevant-files/* > .claude/temp/context-bundle.txt

Gemini consumes

cat .claude/temp/context-bundle.txt | gemini "Analyze this context"

Pattern 2: Gemini → Claude (Result Consumption)

Gemini produces result

gemini "Explore architecture" --output-format json > .claude/temp/gemini-results/exploration.json

Claude parses result

cat .claude/temp/gemini-results/exploration.json | jq -r '.response'

Pattern 3: Persistent Artifacts

For valuable artifacts that should be tracked

result=$(gemini "Create implementation plan" --output-format json) echo "$result" | jq -r '.response' > docs/ai-artifacts/plans/plan-feature-$(date -u +%Y-%m-%dT%H-%M-%SZ).md

Cleanup Strategies

Automatic Cleanup (Session-based)

Clean artifacts older than 7 days

find .claude/temp/gemini-results -type f -mtime +7 -delete find .gemini/temp -type f -mtime +7 -delete

Manual Cleanup

Clear all session artifacts

rm -rf .claude/temp/* rm -rf .gemini/temp/*

Selective Cleanup

Keep recent, delete old

find .claude/temp/gemini-results -name "*.json" -mtime +3 -delete

Best Practices

1. Single Source of Truth

• CLAUDE.md is the authoritative memory file

• GEMINI.md imports from CLAUDE.md and adds overrides

• Don't duplicate information

2. Artifact Lifecycle

• Start in temp directories

• Promote valuable artifacts to docs/ai-artifacts/

• Clean up regularly

3. Clear Naming

• Use descriptive prefixes (exploration-, plan-, analysis-)

• Include timestamps for ordering

• Use ISO 8601 format (sortable)

4. Gitignore Discipline

• Temp directories should always be gitignored

• Memory files should always be tracked

• docs/ai-artifacts/ should be tracked

Related Skills

• gemini-memory-sync

• CLAUDE.md ↔ GEMINI.md synchronization

• gemini-exploration-patterns

• Exploration output standards

• gemini-context-bridge

• Legacy context sharing patterns

Related Commands

• /sync-context

• Synchronize memory files

• /gemini-explore

• Generates exploration reports

• /gemini-plan

• Generates implementation plans

Test Scenarios

Scenario 1: Workspace Setup

Query: "How do I set up a project for Claude and Gemini collaboration?" Expected Behavior:

• Skill activates on "workspace structure" or "cross-cli"

• Provides directory structure and initialization script Success Criteria: User receives complete workspace setup workflow

Scenario 2: Artifact Location

Query: "Where should I store Gemini exploration results?" Expected Behavior:

• Skill activates on "artifact storage" or "where to store"

• Provides location matrix (tracked vs gitignored) Success Criteria: User receives clear guidance on temp vs persistent storage

Scenario 3: Cross-CLI Exchange

Query: "How do I pass context from Claude to Gemini?" Expected Behavior:

• Skill activates on "artifact exchange" or "shared files"

• Provides context handoff pattern Success Criteria: User receives file-based exchange workflow

Version History

• v1.1.0 (2025-12-01): Added MANDATORY section, Test Scenarios, Version History

• v1.0.0 (2025-11-25): Initial release