The fastest way to generate a README with Claude Code is to open your project directory in the terminal and run `claude`, then ask it to analyze your codebase and write a README. Claude Code reads your file tree, source files, and dependencies to produce a structured, accurate README without any plugins or configuration. It works in any language or framework and takes under a minute for most projects.

- No setup required: Claude Code works from your existing project structure
- Supports any stack: Node, Python, Go, Rust, Ruby, and more
- Output is Markdown-formatted and ready to commit

## What is README generation in Claude Code?

Claude Code is Anthropic's agentic CLI tool that runs directly in your terminal. Unlike a chat interface, it has access to your actual filesystem, which means it can read your `package.json`, `pyproject.toml`, source files, and folder structure before writing a single word of documentation. The result is a README that actually reflects what your project does, rather than a generic template you have to fill in.

README generation is one of the most practical uses of Claude Code because it's high-effort to write manually and highly automatable. According to [Anthropic's Claude Code documentation](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan), the tool is designed for "longer-horizon tasks" like documentation, refactoring, and code review directly in your development environment.

## How to generate a README with Claude Code: step by step

### Step 1: open your project in the terminal

Navigate to your project root. Claude Code works best when you start from the directory that contains your primary config file (`package.json`, `Cargo.toml`, `go.mod`, etc.).

```
cd /path/to/your-project
claude
```

### Step 2: give Claude Code a direct prompt

Once the Claude Code session starts, give it a clear, direct instruction. You don't need to over-engineer the prompt. Something like:

```
Generate a comprehensive README.md for this project. Include a project description, installation steps, usage examples, and a list of environment variables.
```

Claude Code will scan your file tree, read key files, and draft the README in one pass. If your project has a specific audience (e.g., a CLI tool vs. a library), mention that in the prompt to sharpen the output.

### Step 3: review and refine with follow-up prompts

Claude Code is conversational. After the first draft, you can iterate:

- `Add a Contributing section with a link to CONTRIBUTING.md`
- `Shorten the installation steps and add a one-liner for Docker`
- `Add badges for build status, license, and npm version`

Each follow-up refines the document without starting over. Claude Code maintains context about your project throughout the session.

### Step 4: write the file to disk

By default, Claude Code may output the README to the terminal. To write it directly, either ask it explicitly:

```
Write the README to README.md in the project root
```

Claude Code will create or overwrite the file. It will ask for confirmation before making filesystem changes, which you can approve inline.

### Step 5: check your usage before running long sessions

README generation for a large, multi-module project can be token-intensive. If you're mid-sprint and hit your [Claude Code usage limit](/content/blog/how-do-i-check-my-claude-code-usage-limits/index.html) halfway through a documentation pass, you'll be locked out for up to 5 hours. Check your remaining usage before starting with the `/usage` command inside a Claude Code session, or at [claude.ai/settings/usage](https://claude.ai/settings/usage).

If you're on macOS and want a persistent view of your usage window, [Usagebar](/content/site-root.html) sits in the menu bar and shows your remaining Claude Code usage at a glance, with alerts at 50%, 75%, and 90% so you're never caught off guard mid-task.

## What to include in your README generation prompt

The quality of Claude Code's output scales directly with the specificity of your prompt. A minimal prompt produces a generic README. A detailed prompt produces documentation that's ready to publish. Here's a breakdown of what to specify:

| Prompt element | Example | Why it matters |
| --- | --- | --- |
| Target audience | "for developers integrating this as a library" | Shapes tone and depth of installation/usage sections |
| Sections to include | "include Prerequisites, Installation, Configuration, and API Reference" | Avoids generic structure, matches your project's needs |
| Code examples | "include real usage examples from the existing tests or examples/ folder" | Claude Code can pull actual working code into the docs |
| Badges | "add shields.io badges for license and latest version" | Adds professionalism with no manual lookup |
| Length | "keep it under 200 lines, optimized for GitHub" | Prevents over-documentation for simple utilities |

## Using slash commands to streamline documentation tasks

Claude Code's [slash commands](/content/blog/how-to-use-claude-code-slash-commands/index.html) can help structure documentation workflows. The `/clear` command resets context between documentation passes so Claude doesn't mix up details from multiple projects. The `/memory` command lets you store project-specific instructions so you don't have to re-specify your README format every session.

For teams, custom slash commands can codify your README template. You define the format once in a `.claude/commands/` file and invoke it with a single command in any project, as detailed in the [full Claude Code slash commands list](/content/blog/claude-code-slash-commands-list/index.html).

### Using /usage to check limits before long documentation passes

Run `/usage` inside any Claude Code session to see your current usage and [when your usage window resets](/content/blog/when-does-claude-code-usage-reset/index.html). For a large monorepo with multiple packages, README generation can run through several back-and-forth iterations. Knowing your remaining capacity prevents an interruption at the worst moment, like right before you're ready to commit and push.

## Common patterns for different project types

### CLI tools

Ask Claude Code to read your argument parser (e.g., `argparse`, `commander`, `cobra`) and generate a full command reference. Example prompt: _"Generate a README that documents all CLI flags and subcommands from the source. Include a quick-start section and a full command reference table."_

### npm / PyPI libraries

Focus on the API surface. Example prompt: _"Generate a README for an npm library. Document all exported functions with type signatures and usage examples. Include an installation one-liner and a badge for the npm version."_

### Internal tools and scripts

Emphasize environment setup. Example prompt: _"Write a README for an internal tool. Assume the reader is a new team member. Document all required environment variables, how to run locally, and how to deploy."_

### Monorepos

Generate per-package READMEs in sequence. Navigate into each package directory and run a Claude Code session per package, or batch the prompt: _"For each package in the /packages directory, generate a README.md in that package's folder."_

## How to monitor usage when doing intensive documentation work

Generating documentation across a large codebase: multiple READMEs, a CONTRIBUTING.md, and inline JSDoc comments in a single session is the kind of task that quietly consumes a significant portion of your usage window. Claude Code's usage is metered in 5-hour windows, and there's no built-in desktop notification when you're running low.

[Usagebar](/content/site-root.html) is a macOS menu bar app built specifically for Claude Code users who want to stay in flow. It shows your live usage percentage at a glance, sends notifications at 50%, 75%, and 90% thresholds, and displays exactly when your window resets so you can plan long documentation passes around your available capacity. Credentials are stored securely in macOS Keychain. Pricing is pay-what-you-want, with a free tier available for students.

## Key takeaways

1. Open your project root in the terminal and start a Claude Code session with `claude`
2. Prompt Claude Code with your README requirements: sections, audience, and examples
3. Iterate with follow-up prompts to refine sections or add missing content
4. Ask Claude Code to write the file to `README.md` once you're satisfied
5. Use `/usage` or [check your limits](/content/blog/how-do-i-check-my-claude-code-usage-limits/index.html) before starting intensive multi-file documentation passes
6. For persistent usage monitoring on macOS, use [Usagebar](/content/site-root.html) to stay informed without leaving your terminal

## Sources

- [Anthropic: Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [Anthropic: Claude usage settings](https://claude.ai/settings/usage)
- [Usagebar: How to use Claude Code slash commands](/content/blog/how-to-use-claude-code-slash-commands/index.html)
- [Usagebar: Claude Code slash commands list](/content/blog/claude-code-slash-commands-list/index.html)
- [Usagebar: When does Claude Code usage reset](/content/blog/when-does-claude-code-usage-reset/index.html)
- [Usagebar: How do I check my Claude Code usage limits](/content/blog/how-do-i-check-my-claude-code-usage-limits/index.html)