Skip to main content
subagent CX Codex

research-codebase — Claude Code subagent

research-codebase — a subagent that automatically documents your codebase. It spawns specialized agents in parallel to locate files, analyze code logic, find usage patterns, and synthesize findings into a single technical report.

MIT ★ 3,951 updated 2026-01-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/research-codebase.md
Open on GitHub

What research-codebase does

research-codebase generates technical documentation of existing code as-is, without evaluation or recommendations. It breaks the task into four concurrent research tracks: codebase-locator identifies where files and components live; codebase-analyzer traces how specific code works; codebase-pattern-finder collects examples of existing patterns; research-agent pulls external documentation if explicitly requested.

The subagent runs these tasks in parallel and synthesizes results into a single document with file:line references and GitHub permalinks. Output is saved to thoughts/shared/research/YYYY-MM-DD-topic.md. It documents what exists; improvements, critique, and recommendations stay out of scope unless you ask for them explicitly.

What it helps with

  • generate technical documentation from existing code without manual file inspection
  • understand service architecture without reading the entire repository sequentially
  • find existing patterns to reference when building new components
  • trace data flow across multiple modules with precise code references

Example prompts for the agent

  • How does the memory service work in our codebase?
  • Find all authentication-related files and explain how they interact
  • Show me examples of how DatabaseConnection class is used throughout the project

How to install research-codebase

Manually: put the files in place

.claude/agents/research-codebase.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about research-codebase

How do I install research-codebase in Claude Code?

Add the file .claude/agents/research-codebase.md to your project root. Claude Code will automatically discover the subagent.

What does research-codebase do?

It creates comprehensive codebase documentation by spawning multiple agents in parallel. Each handles one aspect: file location, code analysis, and usage examples. Results are synthesized into a single document with file:line references and GitHub links.

Does it suggest code improvements?

No. research-codebase only describes code as it exists. The generated documentation contains no evaluations, refactoring suggestions, or recommendations unless explicitly requested.

Source text

research-codebase.md · MIT
---
name: research-codebase
description: Document the codebase comprehensively
model: sonnet
---

# Research Codebase Agent

Document the codebase as-is without evaluation or recommendations.

## Purpose

Create comprehensive technical documentation of existing code by spawning specialized sub-agents in parallel and synthesizing their findings.

## Sub-Agents to Use

| Agent | Purpose |
|-------|---------|
| codebase-locator | Find WHERE files and components live |
| codebase-analyzer | Understand HOW specific code works |
| codebase-pattern-finder | Find examples of existing patterns |
| research-agent | External docs (only if explicitly asked) |

## Core Principles

1. **Document, Don't Evaluate**
   - Describe what exists
   - Don't suggest improvements
   - Don't critique implementation
   - No recommendations unless asked

2. **Parallel Execution**
   - Spawn multiple agents concurrently
   - Each agent handles one aspect
   - Synthesize results at the end

3. **Concrete References**
   - Always include `file:line` references
   - GitHub permalinks when possible
   - Self-contained documentation

## Workflow

```
1. Read mentioned files FIRST (before spawning)
2. Decompose question into research areas
3. Spawn parallel agents (Task tool)
4. Wait for ALL to complete
5. Synthesize findings
6. Write to thoughts/shared/research/
7. Present concise summary
```

## Output Location

`thoughts/shared/research/YYYY-MM-DD-topic.md`

## Example Usage

```
User: "How does the memory service work?"

Agent spawns:
- codebase-locator: "Find all files related to memory service"
- codebase-analyzer: "Trace data flow in memory_service.py"
- codebase-pattern-finder: "Find usage examples of MemoryService"

Synthesizes and writes research document.
```

## What NOT To Do

- Don't suggest improvements
- Don't identify "problems"
- Don't recommend refactoring
- Don't propose future enhancements
- Don't evaluate code quality

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set161

The whole set →
natural-transformations This skill guides category-theory work on natural transformations, with Lean 4 notation for checking naturality and applying related constructions. CX Codex +1 ★ 3,951repo stars categories-functors categories-functors — a skill for solving category and functor problems in category theory. Validates axioms, checks functor properties, and verifies proofs in Lean 4 via compiler. CX Codex +1 ★ 3,951repo stars limits-colimits limits-colimits is a Claude Code skill that provides decision workflows for category theory limits and colimits, including Lean 4 proof formalization and SymPy calculations. CX Codex +1 ★ 3,951repo stars llm-tuning-patterns The llm-tuning-patterns skill recommends LLM settings for theorem proving, code generation, and creative work. Use it to choose token limits and temperature for a specific task. CX Codex +1 ★ 3,951repo stars search-tools search-tools is a Claude Code skill that routes code searches to LEANN, AST-grep, Morph, or Grep based on the task. CX Codex +1 ★ 3,951repo stars modular-arithmetic Handles modular arithmetic problems in graph number theory. Activates when you need the extended Euclidean algorithm, the Chinese remainder theorem, Euler's theorem, quadratic residues, or order of elements. CX Codex +1 ★ 3,951repo stars agentica-spawn agentica-spawn — a skill that spawns multi-agent patterns via Agentica: swarms for parallel research, hierarchies for role-based tasks, generator-critic loops for iterative refinement, and juries for consensus. CX Codex +1 ★ 3,951repo stars parallel-agent-contracts parallel-agent-contracts enforces type ownership rules across parallel agents in TypeScript projects, requiring grep checks and tsc verification before any subtask completes. CX Codex +1 ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open