Claude and Gemini Integration Protocol

Hypothesis

Can Claude Code and Gemini CLI be combined in a unified workflow where each AI reads standardized documentation to understand work done and anticipated next steps, eliminating API calls and context waste?

Approach

1. Analyzed complementary strengths of Claude (complex reasoning, quality coding) and Gemini (large codebase analysis, rapid execution)
2. Designed file-based “State of Play” protocol for context transfer
3. Established Read-Execute-Write SOP for hot-swapping between agents

Findings

Key Observations

Task Separation Strategy:

Task Type	Recommended Tool	Rationale
High-level planning & reasoning	Claude Code	Excels at structuring problems
Large codebase analysis	Gemini CLI	Vast context window
Detailed implementation	Claude Code	Higher quality, cleaner code
Rapid prototyping	Gemini CLI	Faster generation
Code review	Gemini CLI	External perspective
Orchestration	Claude Code	Primary agent role

The State of Play Protocol:

Introduced .context/active_state.md file as the “baton” passed between agents:

# PROJECT STATE [TIMESTAMP]
 
## 1. High-Level Objective
 
(Single sentence North Star for current sprint)
 
## 2. Phase Status
 
- [x] Phase 1: Completed
- [>] Phase 2: IN PROGRESS
- [ ] Phase 3: Pending
 
## 3. The Brain Dump (Handoff)
 
- Last Actor: [Claude/Gemini]
- Key Decision: [Recent decision]
- Current Blocker: [Active blocker]
- Next Immediate Action: [Specific action]
 
## 4. Context Pointers
 
- Plan: ../.planning/roadmap.md
- Metrics: ../.management/kpi.md

Read-Execute-Write Workflow:

1. Ingest: Agent reads active_state.md, confirms understanding
2. Execute: Agent performs work
3. Handover: Agent updates active_state.md before session ends

Integration Methods

1. Shell Command Invocation: Claude calls Gemini via ! gemini -p "prompt"
2. Sub-agent Pattern: MCP wrapper for programmatic delegation
3. Shared Workspace: Postbox files (todo.md → completed.md)
4. External Orchestration: Shell scripts managing parallel sessions

Outcome

Status: Partial

Protocol design complete. Implementation requires:

• Creating .context/ directories across 13 apps
• Establishing shell aliases for standard macros
• Testing hot-swap scenarios

Next Steps

• Implement .context/active_state.md in pilot project
• Create shell aliases for ingest/handover macros
• Test Claude→Gemini→Claude round-trip
• Document edge cases and failure modes

Related

• MCP Security - Security patterns for agent workflows
• Systematic Debugging - Debugging patterns
• Procedural Generation - Multi-agent code generation