Skip to main content
command CX Codex

bootstrap-repo — Claude Code command: what it does, how to install

bootstrap-repo runs 10 parallel subagents to analyze repository structure and writes an architectural overview into CODEBASE.md.

MIT ★ 1,424 updated 2026-10-06

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

What bootstrap-repo does

The command starts by inspecting the repository root with git and file matching to identify primary frameworks. Next, it dispatches 10 background subagents in a single message using the Task tool. Each agent reviews a dedicated area: directory layout, package dependencies, architecture style, data layer, API surface, test suites, CI/CD pipelines, security patterns, existing documentation, and domain concepts.

Once all background tasks finish, the command combines their summaries into CODEBASE.md at the project root. The resulting file contains an ASCII architecture diagram, entry points, dependency tables, and interface definitions. Execution fails if access to Read, Write, Edit, Glob, Grep, Bash, or Task is missing.

What it helps with

  • map the architecture of an unfamiliar codebase
  • generate an ASCII diagram of system components
  • audit dependencies, test suites, and CI/CD pipelines in parallel
  • document data schemas and external interfaces in CODEBASE.md

Example prompts for the agent

  • /bootstrap-repo
  • Run /bootstrap-repo to inspect the project architecture
  • Generate CODEBASE.md using /bootstrap-repo

How to install bootstrap-repo

Manually: put the files in place

.claude/commands/bootstrap-repo.md

Call it with /bootstrap-repo. For all projects use ~/.claude/commands/

Questions about bootstrap-repo

How to install bootstrap-repo in Claude Code?

Place the command prompt file at .claude/commands/bootstrap-repo.md.

What does bootstrap-repo do?

It deploys ten parallel subagents to inspect project internals and synthesizes the findings into a root CODEBASE.md document.

Which tools must be permitted for bootstrap-repo?

The command requires execution permissions for Read, Write, Edit, Glob, Grep, Bash, and Task.

Source text

bootstrap-repo.md · MIT
---
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
description: Explore the repository with 10 parallel subagents to create comprehensive documentation. Creates CODEBASE.md with full architecture analysis.
---

# Bootstrap Repository

Perform a comprehensive exploration of the current repository using 10 parallel subagents, then synthesize findings into a single CODEBASE.md document.

## Phase 1: Initial Scan

Before spawning subagents, gather basic repo info:

```bash
git remote -v
git log --oneline -5
```

Use Glob to identify the project root and top-level structure:

- Check for `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Makefile`, `Dockerfile`, etc.
- Identify the primary language and framework

## Phase 2: Spawn 10 Exploration Subagents (Parallel)

**CRITICAL**: Launch ALL 10 Task calls in a SINGLE message for true parallelism. Each subagent uses `run_in_background: true`.

```
[Task 1]
description: "File Structure Explorer"
prompt: "Map the complete directory tree of this repository. Identify:
- Top-level directory purposes (src/, lib/, tests/, docs/, etc.)
- Entry points (main files, index files, app files)
- Configuration files and their roles
- Generated vs source directories
- File count and language breakdown by directory
Report a structured tree with annotations for each directory's purpose."
run_in_background: true

[Task 2]
description: "Dependency Analyzer"
prompt: "Analyze all dependency files in this repository:
- Package manifests (package.json, pyproject.toml, Cargo.toml, go.mod, etc.)
- Lock files and their state
- Direct vs transitive dependency count
- Key dependencies and what they provide (framework, ORM, HTTP client, etc.)
- Dev dependencies and their purposes
- Any outdated or pinned versions worth noting
Report a categorized dependency inventory."
run_in_background: true

[Task 3]
description: "Architecture Mapper"
prompt: "Determine the high-level architecture of this project:
- Architectural style (monolith, microservices, serverless, plugin system, CLI, library)
- Layer structure (presentation, business logic, data access)
- Module boundaries and how they communicate
- Key abstractions and interfaces
- Configuration management approach
- Error handling patterns
Create an ASCII architecture diagram showing component relationships."
run_in_background: true

[Task 4]
description: "Data Layer Analyst"
prompt: "Analyze the data layer of this repository:
- Database type and ORM/query builder used
- Schema definitions or migrations
- Models/entities and their relationships
- Data validation approach
- Caching strategy (if any)
- File-based storage or state management
If no database exists, analyze how state and data are managed (files, config, in-memory)."
run_in_background: true

[Task 5]
description: "API Surface Mapper"
prompt: "Map all external-facing interfaces:
- HTTP/REST/GraphQL endpoints with methods and paths
- CLI commands and their arguments
- Library exports and public API
- Event handlers or message consumers
- Webhook endpoints
- Plugin interfaces or extension points
For each interface, note its purpose and any authentication requirements."
run_in_background: true

[Task 6]
description: "Testing Analyst"
prompt: "Evaluate the testing setup:
- Test framework(s) used
- Test directory structure
- Types of tests present (unit, integration, e2e, snapshot)
- Test configuration files
- Coverage configuration and thresholds
- Test utilities, fixtures, and helpers
- How to run the tests (commands)
- Approximate test count and coverage level"
run_in_background: true

[Task 7]
description: "Deployment Analyst"
prompt: "Analyze deployment and CI/CD configuration:
- CI/CD pipeline files (.github/workflows, .gitlab-ci.yml, Jenkinsfile, etc.)
- Dockerfile and docker-compose configurations
- Infrastructure-as-code (Terraform, Pulumi, CloudFormation)
- Environment configuration (.env.example, config files)
- Build scripts and output
- Release/versioning strategy
- Deployment targets (cloud provider, platform)"
run_in_background: true

[Task 8]
description: "Security Reviewer"
prompt: "Perform a security-oriented scan:
- Authentication and authorization mechanisms
- Secret management approach (.env, vault, etc.)
- Input validation and sanitization patterns
- CORS, CSP, and other security headers
- Dependency vulnerability indicators
- File permission patterns
- Any security-related middleware or hooks
Note: Do NOT report actual secret values, only patterns."
run_in_background: true

[Task 9]
description: "Documentation Auditor"
prompt: "Catalog existing documentation:
- README files and their completeness
- API documentation (Swagger, JSDoc, docstrings)
- Architecture decision records (ADRs)
- Contributing guides
- Changelog and versioning docs
- Inline code documentation quality
- Configuration documentation
Rate documentation completeness: None / Minimal / Moderate / Comprehensive"
run_in_background: true

[Task 10]
description: "Domain Model Analyst"
prompt: "Understand the business domain:
- Core domain concepts and entities
- Business rules encoded in the codebase
- Domain-specific terminology (build a glossary)
- Workflows and state machines
- Validation rules and constraints
- Key algorithms or business logic
Report a domain glossary and concept map."
run_in_background: true
```

## Phase 3: Collect Results

Each subagent returns its result automatically when it completes — there is no
separate retrieval call. Launch the `Task` calls in a single message, then read
each returned summary as it finishes.

## Phase 4: Synthesize into CODEBASE.md

Combine all subagent findings into a single `CODEBASE.md` at the project root. Use this structure:

````markdown
# [Project Name] - Codebase Documentation

> Auto-generated by bootstrap-repo on YYYY-MM-DD

## Overview

[2-3 sentence summary: what the project is, its primary purpose, and tech stack]

## Architecture

[ASCII diagram of component relationships]

```
+-------------------+
|    Component A    |
+---------+---------+
          |
          v
+---------+---------+
|    Component B    |
+-------------------+
```

### Architectural Style

[Monolith / Microservices / Serverless / Library / CLI / Plugin / etc.]

### Key Design Decisions

- [Decision] -- [Rationale]

## Project Structure

```
repo-root/
├── src/      -- [purpose]
├── tests/    -- [purpose]
├── docs/     -- [purpose]
└── ...
```

### Entry Points

- `path/to/main` -- [what it does]

## Dependencies

### Runtime

| Package | Purpose        |
| ------- | -------------- |
| pkg-a   | HTTP framework |

### Development

| Package | Purpose     |
| ------- | ----------- |
| pkg-b   | Test runner |

## Data Layer

[Database, ORM, schema summary, key models and relationships]

## API Surface

### [Interface Type: REST / CLI / Library / etc.]

| Endpoint/Command | Method | Purpose     |
| ---------------- | ------ | ----------- |
| /api/foo         | GET    | Fetches foo |

## Testing

- **Framework**: [name]
- **Run command**: `[command]`
- **Coverage**: [level or percentage]
- **Test types**: [unit, integration, e2e]

## Deployment

- **CI/CD**: [platform]
- **Runtime**: [Docker, serverless, etc.]
- **Environments**: [dev, staging, prod]

## Security

- **Auth**: [mechanism]
- **Secrets**: [management approach]
- **Key patterns**: [validation, sanitization]

## Documentation Status

[None / Minimal / Moderate / Comprehensive] -- [summary of what exists]

## Domain Glossary

| Term | Definition                    |
| ---- | ----------------------------- |
| term | what it means in this project |

## Key Workflows

1. **[Workflow name]**: [step-by-step description]
````

### Rules for CODEBASE.md

- **Accuracy over completeness**: Only include what the subagents actually found. Do not speculate.
- **Concise entries**: Favor tables and bullet points over paragraphs.
- **ASCII diagrams**: Use box-drawing characters for architecture visualization. Keep diagrams under 30 lines.
- **Relative paths**: Use paths relative to repo root.
- **No secrets**: Never include actual credentials, tokens, or keys.

## Phase 5: Summary

After writing CODEBASE.md, print a summary:

```
## Bootstrap Complete

- **Project**: [name]
- **Language**: [primary language]
- **Architecture**: [style]
- **Files analyzed**: ~[count]
- **Documentation written**: CODEBASE.md ([line count] lines)
- **Subagents used**: 10 (parallel)

### Quick Stats
- Dependencies: X runtime, Y dev
- API endpoints: Z
- Test coverage: [level]
- Documentation status: [rating]
```

## When to Use

- Onboarding onto a new codebase
- Starting a major refactoring effort
- Preparing for an architecture review
- Creating documentation for a previously undocumented project
- Understanding an inherited or open-source project

© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set46

The whole set →
parallel-execution parallel-execution — a skill for launching several independent tasks simultaneously using the Agent tool. Speeds up work by a factor of N when tasks don't depend on each other. CX Codex +1 ★ 1,424repo stars tutorial tutorial is a Claude Code command that introduces plugin agents, commands, hooks, and skills through practical examples without editing project files. CX Codex +1 ★ 1,424repo stars security-auditor security-auditor audits code for common vulnerabilities, weak access controls, and risky configuration. Use it when working with authentication, secrets, or user-supplied input. CX Codex ★ 1,424repo stars refactorer refactorer — a subagent that improves code structure: extracts methods and classes, eliminates duplication, applies design patterns. Works step-by-step, runs tests before and after each change. CX Codex ★ 1,424repo stars test-architect test-architect — a Claude Code subagent for test planning, test writing, coverage checks, and flaky-test analysis. Use it when changing features or fixing bugs. CX Codex ★ 1,424repo stars devops-infrastructure devops-infrastructure — a skill for writing Dockerfiles, configuring CI/CD pipelines, planning deployments, and setting up observability. CX Codex +1 ★ 1,424repo stars database-design database-design guides database schema modeling, query tuning, indexing strategies, and zero-downtime migration workflows for SQL and NoSQL databases. CX Codex +1 ★ 1,424repo stars orchestrator orchestrator plans multi-step work, hands independent tasks to specialist subagents, and combines their results. Use it for changes across modules or GitHub PR workflows. CX Codex ★ 1,424repo stars

Project sponsors

Companies that keep this analytics open