Deep Repository Analysis

Lesson updated November 3, 2026 based on the Codex manual: “Deep Research for GitHub” is not a Codex feature. Repository analysis is performed with Codex in read-only mode, while deep research is a ChatGPT Work feature, availability depending on your account and workspace. The previous version’s unsourced comparison table of durations has been removed. Sources: Codex CLI · Non-interactive mode.

Before modifying code, you often need to understand it first: the architecture of a legacy project, its dependencies, and its technical debt. Two tools fit this bill. Codex analyzes a repository from the inside—it reads files, examines Git history, and runs diagnostic commands—without making any changes. ChatGPT Work’s deep research conducts investigations across multiple sources and delivers a sourced report; it is the right tool for questions that go beyond the repository, such as evaluating an external library.

Analyze Without Modifying Anything

A standard Codex task executes an action: writing code, fixing a bug, or generating tests. For analysis, ask Codex to synthesize without modifying anything, and give it the means to stick to that constraint. Set the session to read-only (/permissions, mode read-only), or run the analysis with codex exec, which defaults to a read-only sandbox. It can scan hundreds of files, examine Git history, and produce a detailed report. This difference shows up immediately in your prompt, which should focus on understanding rather than modification:

"Analyze the architecture of this project without modifying any files. 
How does data flow from the API to the database? What patterns are 
used? Where are the fragility points?"

The result is not a commit but a structured document containing references to relevant files and recommendations. You review it, discuss it in a technical meeting, and correct it where it is wrong.

Accelerate Technical Onboarding

When a developer joins a team, they usually spend their first two weeks mentally reconstructing a map that no one ever wrote down: which service calls what, why a module has a name that no longer matches its content, or where the billing logic hides. Codex can draw this map for them:

"Analyze this repository and generate an onboarding guide 
for a new developer. Cover:
- General architecture and layers
- Naming and structure conventions
- End-to-end flow of a typical request
- The most important files to read first
- Common pitfalls and project-specific quirks"

The resulting document serves as a reference during the first few weeks and gets corrected as the team provides feedback. This correction exercise has an unexpected benefit: it reveals blind spots that no one bothered to document because “everyone knows how it works.”

Audit Dependencies and Technical Debt

The second natural use case is inventory. A three-year-old codebase accumulates abandoned libraries, functional duplicates, and dead imports that no one dares to delete due to a lack of overview:

"Analyze all project dependencies (package.json 
and lock file). Identify:
- Obsolete packages (last update > 1 year ago)
- Known vulnerabilities
- Duplicate packages (same functionality)
- Unused packages (imported nowhere)
- Packages with incompatible licenses"

This analysis cross-references package.json, the lock file, and the imports actually present in the code. For known vulnerabilities and package maintenance status, it needs public data, so you must explicitly allow network access or use your package manager’s audit tools (such as npm audit). Evaluating technical debt follows the same logic, with one additional requirement—the last line of the prompt. Without sorting criteria, you get a list of forty problems with no idea where to start.

"Evaluate the technical debt of this project. Analyze:
- Cyclomatic complexity of core modules
- Most frequently modified files (Git hotspots)
- Code duplication patterns
- Unresolved TODOs and FIXMEs
- Test coverage by module
Rank problems by impact and effort to fix."

The value of these analyses lies in the ratio of time invested to results obtained: a few precise instructions replace days of reading. Measure this on your own projects rather than relying on generic estimates, and always review the report: the agent can be wrong, especially about what the repository does not contain.

Evaluate an External Project Before Adoption

For an open-source library you are considering adopting, the question goes beyond the repository: release frequency, issue activity, and reputation. This is the domain of ChatGPT Work’s deep research. In the desktop app, switch to Work, open Plugins, and select Deep research; on the web, open the + menu in a Work conversation. Availability depends on your account and workspace:

"Analyze the repository github.com/org/library. 
Evaluate its maturity:
- Release frequency and maintenance
- Documentation quality
- Community activity (issues, PRs)
- Test coverage
- Recommendation: Is it safe to adopt in production?"

This is the verification step we almost always skip because we cannot spare half a day for it, yet its absence costs us two years later: the library is no longer maintained, its sole maintainer has vanished, and you are left with a dependency you must rewrite in a hurry.

Get Actionable Reports

Report quality depends directly on prompt precision. “Where are the fragility points?” yields a far more useful result than “Analyze the project” because the first formulation imposes an angle and forces a hierarchy. Also request an explicit format—“rank by priority,” “organize by module”—to get a document you can scan rather than read cover to cover. Then follow up with concrete Codex tasks that fix the identified problems. At that point, the analysis stops being just another report and becomes the starting point for a work plan. Finally, share these reports with your team, as their value grows with the number of people who refer to them daily.

Key Takeaways

To analyze a repository, run Codex in read-only mode (/permissions, or codex exec, which is read-only by default)
Ideal for onboarding, audits, and technical debt evaluation
ChatGPT Work’s deep research suits multi-source questions, such as evaluating an external library
Results feed into concrete Codex tasks to fix identified problems
Review every report: an agent can be wrong, especially about missing content