Using Gemini CLI for Quick Repository Archaeology
Start with a clean repository snapshot
When I inherit a codebase, I want a map before I want a patch. Gemini CLI is useful for that first pass because it can inspect files from the terminal and answer questions in the context of the repository. Start by checking where you are and what is already changed:
- Run pwd to confirm that your shell is at the repository root.
- Run git status --short to see whether your working tree has existing changes.
- Run rg --files -g '!node_modules' -g '!vendor' -g '!dist' | head -80 to sample the project structure.
Keep the file listing small. A repository with generated output or vendored dependencies can overwhelm a useful first question. The goal is to identify likely entry points, not to read every file at once.
Ask Gemini CLI for the repository map
Install the CLI if it is not already available, authenticate using the method your environment supports, then start it from the repository root:
npm install -g @google/gemini-cli — gemini — Give it a bounded task: “Map this repository for a developer new to the code. Identify the application entry points, major modules, test commands, and configuration files. Cite file paths for each finding. Do not modify files.”
That last sentence matters. During archaeology, I want evidence and orientation, not an unsolicited refactor. Ask follow-up questions in the same session, such as “Where is request authentication handled?” or “Trace the path from this CLI command to its network request.” Request file paths and function names so you can verify the answer quickly.
Trace one behavior instead of reading everything
Choose a concrete behavior that matters to your task: a route, a command, a background job, or a configuration option. Ask Gemini CLI to follow that behavior from its entry point to its side effects, and to distinguish confirmed facts from guesses.
For example: “Trace how the application handles POST requests to the health endpoint. Show the route registration, handler, relevant middleware, and tests. Use only files in this repository, and cite paths and symbols.”
Then check the citations yourself. Open the named files with sed -n '1,180p' path/to/file, search for symbols with rg -n 'symbolName' ., and inspect the relevant test. This is a short feedback loop: the model narrows the search, while the repository remains the source of truth.
Build a test and configuration checklist
Before changing code, ask which commands validate the area you traced. A useful prompt is: “Find the documented and configured test commands for this module. Identify the smallest relevant test target, required environment variables, and any setup steps. Cite the files that establish each answer.”
Compare the response against package scripts, build files, CI workflows, and contributor documentation. For a JavaScript project, inspect package.json with sed -n '1,180p' package.json; for CI, locate workflows with rg --files .github/workflows. Run the smallest relevant test first, then broaden coverage if the change crosses module boundaries.
When you need a second perspective, Fluxo provides one key and one base URL, https://api.fluxorelay.com, for Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and more. It works with Gemini CLI, Claude Code, Codex, and any OpenAI SDK; usage is billed per real token, including cache reads and writes, without a monthly fee. The available shelf includes Gemini 3.1 Pro and DeepSeek V4 Flash, among other models. If that setup fits your workflow, you can create a Fluxo account and use the same relay across your editor and terminal tools.
Keep the notes useful after the first session
Finish by asking Gemini CLI to summarize only what you verified: “Write a concise repository map with entry points, test commands, and the files involved in this behavior. Mark anything not confirmed by source or tests as an open question. Do not edit files.” Save the result in your own working notes, not automatically in the project.
Good repository archaeology reduces the number of files you need to open, but it does not replace opening them. Start broad, trace one behavior, verify every important claim, and let the first test run expose what the map missed.