How to run Claude Code and Gemini CLI on the same project

Claude Code uses CLAUDE.md. Gemini CLI uses GEMINI.md. Cursor uses .cursorrules. GitHub Copilot reads AGENTS.md. If you or your team uses more than one of these tools, you now have a configuration management problem that did not exist six months ago.

The most common multi-tool combination right now is Claude Code and Gemini CLI. Claude Code for heavy implementation work. Gemini CLI for quick tasks, code review, or getting a second opinion. Both are terminal-native, both read project config files, and both work well on the same codebase. The challenge is keeping the configurations consistent.

This guide covers the practical setup for running both tools on the same project, how the config files differ, and how to prevent them from drifting apart over time.

What each tool reads

Claude Code loads these files at session start:

• CLAUDE.md in the project root (primary configuration)
• .claude/rules/*.md for additional rule files (loaded on demand)
• ~/.claude/CLAUDE.md for global user-level configuration

Gemini CLI loads:

• GEMINI.md in the project root
• Additional context files as referenced in GEMINI.md

Each tool ignores the other's files. Having both CLAUDE.md and GEMINI.md in your project root causes no conflicts. Git tracks both, your team can use whichever tool they prefer, and the project supports both without anyone having to choose.

What goes in both files

The core project information should be identical in both configs. This is the information that any AI tool needs to work well with your codebase:

• Project description and purpose
• Directory structure and file organization
• Language and framework versions
• Coding conventions (naming, imports, patterns)
• Test commands and how to run them
• Build commands
• Common tasks and how to perform them

This information is the same regardless of which tool reads it. The difference is in how you format it and what tool-specific features you add on top.

What differs between the files

CLAUDE.md-specific sections:

• Subagent configuration (how to use parallel agents for complex tasks)
• Tool use preferences (which tools to prefer or avoid)
• Context management rules (what to read first, tiered loading)
• Hook configuration references
• Memory and session continuity instructions

GEMINI.md-specific sections:

• Google service integration preferences
• Output format instructions (Gemini handles formatting directives differently)
• Model-specific behavior adjustments
• Extension and plugin references

The tool-specific sections make up maybe 20-30% of each file. The remaining 70-80% is the same project information expressed in slightly different formatting.

Keeping configs in sync

Config drift is the main risk of maintaining multiple files. Someone updates the test command in CLAUDE.md but forgets GEMINI.md. A new coding convention gets added to one file but not the other. Over weeks, the files diverge and the tools start behaving differently on the same project.

There are three approaches to managing this:

Approach 1: shared conventions file

Create a CONVENTIONS.md file that contains all the shared project information. Reference it from both CLAUDE.md and GEMINI.md. Each tool-specific file contains only the tool-specific configuration plus a note to read CONVENTIONS.md for project details.

This works well for teams. One person maintains the conventions. Each developer maintains their preferred tool config. The shared information stays in one place.

Approach 2: generate from a single source

Use a tool like ContextKit to generate both files from the same inputs. Answer the project questions once, export in CLAUDE.md format, then export again in GEMINI.md format. The core information is identical because it came from the same source. You customize the tool-specific sections afterward.

When conventions change, regenerate both files from the updated inputs. This is the lowest-maintenance approach for projects that do not change their tooling frequently.

Approach 3: CI enforcement

Add a CI check that compares the key sections of both files. You can write a simple script that extracts project structure, conventions, and test commands from both files and fails the build if they have diverged. This is the most rigorous approach but requires some initial setup.

For teams that take this seriously, npx contextkit score can check both files in CI and enforce a minimum quality threshold on each. If someone updates CLAUDE.md but lets GEMINI.md degrade, the CI check catches it.

Practical multi-tool workflow

Here is how developers who use both tools typically organize their work:

Claude Code for implementation. When you are building features, refactoring code, or doing complex multi-file changes, Claude Code's agentic capabilities (subagents, long-running sessions, tool use) make it the stronger choice. It handles the "build this feature from spec" type of work well.

Gemini CLI for review and quick tasks. For getting a second opinion on code, quick questions about APIs, or tasks where you want a different perspective, Gemini CLI provides value as a complement rather than a replacement. If Claude Code suggested an approach and you are not sure about it, asking Gemini for its take gives you two independent assessments.

Either tool for code review. Running both tools as reviewers on the same PR catches different things. In our experience, they tend to flag different issues. The overlap gives you confidence in the shared findings. The differences point to things worth investigating further.

Switch tools when stuck. If you have been going back and forth with one tool on a problem and not making progress, switching to the other tool with a fresh session often breaks the deadlock. Each model has different strengths and different failure modes. A problem that confuses one model might be straightforward for the other.

File structure for a multi-tool project

Here is what the root of a multi-tool project looks like:

project-root/
  CLAUDE.md           # Claude Code configuration
  GEMINI.md           # Gemini CLI configuration
  .cursorrules        # Cursor configuration (if applicable)
  AGENTS.md           # GitHub Copilot / multi-agent config
  .claude/
    rules/            # Claude-specific rule files
      testing.md
      security.md
  src/
  tests/
  ...

Each tool has its own config file and rules directory. The .claude/ and .gemini/ directories are separate. Git tracks everything. Team members use whichever tool they prefer without affecting anyone else.

Getting started with a multi-tool setup

If you already have a CLAUDE.md and want to add Gemini CLI support (or vice versa), the fastest path is:

1. Go to ContextKit's generator and answer the 5 questions about your project.

2. Export as CLAUDE.md format. Compare it with your existing file. Keep your existing file if it is more detailed, but note any sections the generator suggests that you are missing.

3. Export as GEMINI.md format. This gives you a baseline GEMINI.md with the same project information.

4. Customize the tool-specific sections in each file.

5. Score both files with the Analyzer to check for gaps.

The whole process takes about 10 minutes and gives you a consistent multi-tool configuration from a single source of project information.