codebrief

Instantly understand any codebase. One command.

# Run directly from GitHub (available now)
npx github:Android-Tipster/codebrief

# Or install from npm (coming soon)
npx codebrief

codebrief scans your project, sends the most important files to Claude AI, and generates a CODEBASE.md that explains the architecture, key files, data flows, and a day-one onboarding guide. No config. No install. Just run it.

Why

You just cloned a repo. Or inherited one. Or you're reviewing a PR in a codebase you barely know.

Reading every file takes hours. Asking a coworker takes interrupting them. Asking ChatGPT gives you generic nonsense because it doesn't see your actual code.

codebrief reads the actual source files, finds the ones that matter, and gives you a document you can open in Cursor, Obsidian, or Notion and actually use.

Quick Start

1. Get an Anthropic API key at console.anthropic.com

2. Set it:

export ANTHROPIC_API_KEY=sk-ant-...

3. Run it in your project directory:

npx github:Android-Tipster/codebrief

That's it. CODEBASE.md appears in your current directory.

What Gets Generated

# my-project — Codebase Guide

## What This Project Does
...

## Tech Stack
...

## Architecture Overview
...

## Entry Points
...

## Key Files
...

## Data Flow
...

## Developer Onboarding Checklist
...

Examples

# Analyze current directory
npx github:Android-Tipster/codebrief

# Analyze a specific subfolder
npx github:Android-Tipster/codebrief ./src

# Save to a custom path
npx github:Android-Tipster/codebrief --output docs/architecture.md

# Print to terminal instead of saving
npx github:Android-Tipster/codebrief --no-save

# Analyze more files (slower but more thorough)
npx github:Android-Tipster/codebrief --max-files 40

# See what's happening under the hood
npx github:Android-Tipster/codebrief --verbose

How It Works

1. Scans your project for source files (.js, .ts, .py, .go, .rs, .rb, .java, and more)
2. Filters noise: skips node_modules, dist, .git, build dirs, and files that won't help a developer understand the project
3. Prioritizes entry points, config files, and high-level modules first
4. Respects .gitignore so it doesn't send garbage to the API
5. Sends the top 25 files (configurable) to Claude Haiku
6. Returns a structured Markdown document you can commit, share, or keep private

All this happens with zero telemetry. Your code goes from your filesystem to Anthropic's API (using your key) and nowhere else.

Supported Languages

JavaScript, TypeScript, Python, Go, Rust, Ruby, Java, C/C++, C#, PHP, Swift, Kotlin, Scala, R, Shell scripts, SQL, GraphQL, Prisma, Terraform, and more.

Options

| Flag | Default | Description | |------|---------|-------------| | [directory] | . | Path to analyze | | --output, -o | CODEBASE.md | Output file path | | --no-save | off | Print to stdout | | --max-files | 25 | Max files to analyze | | --verbose | off | Show progress details | | --format | markdown | Output format |

Requirements

• Node.js 18+
• An Anthropic API key

Cost per run: approximately $0.001–0.005 (Claude Haiku pricing). Under half a cent.

Tips

Commit it. CODEBASE.md is useful as a living document. Regenerate it after major refactors.

Point it at a subfolder. npx codebrief ./api analyzes just one layer of a monorepo.

Use --no-save in scripts. Pipe the output into other tools: npx codebrief --no-save | pbcopy

License

MIT

Built with

Claude Haiku for AI analysis. No frameworks, no dependencies — just Node.js built-ins.

Made by Noah Albert