{"_id":"@amritessh/claude-onboard","name":"@amritessh/claude-onboard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@amritessh/claude-onboard","version":"0.1.0","description":"Generate CLAUDE.md and ARCHITECTURE.md for any GitHub repo or local project","main":"dist/index.js","bin":{"claude-onboard":"dist/index.js"},"scripts":{"build":"tsc -b","dev":"tsc -b --watch","start":"node dist/index.js"},"dependencies":{"@anthropic-ai/sdk":"^0.39.0","@octokit/rest":"^19.0.0","commander":"^12.0.0"},"devDependencies":{"typescript":"^5.4.0"},"_id":"@amritessh/claude-onboard@0.1.0","gitHead":"970c01bfec5e3e661a058eeee294ca390a74800a","types":"./dist/index.d.ts","_nodeVersion":"20.18.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-698IRYk5U/QICmSv6cCTkcrX1vRUnqofoRAw6lzSNY3rhAOBKuTJeDru2kPSQb7Yr42/zPWrg6/iUWyCUfPkpA==","shasum":"9f16af67399bf70acbe02c2dc2a5aac33ce048d2","tarball":"https://registry.npmjs.org/@amritessh/claude-onboard/-/claude-onboard-0.1.0.tgz","fileCount":29,"unpackedSize":63701,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQChkrYICM7/Ec5dwZLSj0930FVkDEncQkog/EvCIEizSwIgXN2BOHHqfwxUkgjnVx9TbeC8g0AzbckqQFNEabFUzjc="}]},"_npmUser":{"name":"amritessh","email":"amriteshanand7@gmail.com"},"directories":{},"maintainers":[{"name":"amritessh","email":"amriteshanand7@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-onboard_0.1.0_1774908529336_0.579372019389365"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-30T22:08:49.176Z","0.1.0":"2026-03-30T22:08:49.520Z","modified":"2026-03-30T22:08:49.788Z"},"maintainers":[{"name":"amritessh","email":"amriteshanand7@gmail.com"}],"description":"Generate CLAUDE.md and ARCHITECTURE.md for any GitHub repo or local project","readme":"# claude-onboard\n\n**Generate a production-quality `CLAUDE.md` and `ARCHITECTURE.md` for any codebase in seconds.**\n\n[![npm version](https://img.shields.io/npm/v/claude-onboard)](https://www.npmjs.com/package/claude-onboard)\n[![npm downloads](https://img.shields.io/npm/dm/claude-onboard)](https://www.npmjs.com/package/claude-onboard)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n\n`claude-onboard` reads your repository — source files, configs, directory structure, git history — and uses Claude AI to generate two documents that make onboarding and AI-assisted development dramatically faster:\n\n- **`CLAUDE.md`** — the context file Claude Code reads before every session. Tells AI assistants exactly how your project works, what commands to run, what conventions to follow, and what to avoid.\n- **`ARCHITECTURE.md`** — a technical map of your system with component diagrams, data flow descriptions, and key design decisions.\n\nPoint it at any GitHub URL or local folder. Works on any language. No configuration needed.\n\n![Demo](demo.gif)\n\n---\n\n## Why this exists\n\n[Claude Code](https://claude.ai/code) and other AI coding tools work dramatically better when they understand your project's context. A good `CLAUDE.md` file can halve the number of back-and-forth messages needed to complete a task, prevent AI tools from violating your conventions, and give new contributors an immediate mental model of the codebase.\n\nWriting a good `CLAUDE.md` manually takes 1–2 hours. `claude-onboard` does it in 30 seconds.\n\n---\n\n## Installation\n\n```bash\n# Run without installing (recommended)\nnpx @amritessh/claude-onboard <target>\n\n# Or install globally\nnpm install -g @amritessh/claude-onboard\n```\n\n### Requirements\n\n- Node.js 18+\n- An Anthropic API key ([get one here](https://console.anthropic.com))\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\n---\n\n## Usage\n\n### On a GitHub repository\n\n```bash\n# Full URL\nnpx @amritessh/claude-onboard https://github.com/expressjs/express\n\n# Short form\nnpx @amritessh/claude-onboard expressjs/express\n\n# Private repo (requires token)\nnpx @amritessh/claude-onboard https://github.com/your-org/private-repo --github-token ghp_...\n```\n\n### On a local project\n\n```bash\n# Current directory\nnpx @amritessh/claude-onboard .\n\n# Specific path\nnpx @amritessh/claude-onboard ~/projects/my-app\n\n# Write to a custom output directory\nnpx @amritessh/claude-onboard . --output-dir ./docs\n\n# Preview without writing files\nnpx @amritessh/claude-onboard . --dry-run\n\n# Only generate CLAUDE.md (skip ARCHITECTURE.md)\nnpx @amritessh/claude-onboard . --no-architecture\n```\n\n### In CI (keep docs fresh on every release)\n\n```yaml\n# .github/workflows/update-docs.yml\nname: Update onboarding docs\non:\n  push:\n    branches: [main]\n\njobs:\n  update-docs:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Generate docs\n        run: npx @amritessh/claude-onboard . --output-dir ./docs\n        env:\n          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n      - name: Commit if changed\n        run: |\n          git config user.name \"github-actions[bot]\"\n          git config user.email \"github-actions[bot]@users.noreply.github.com\"\n          git add docs/CLAUDE.md docs/ARCHITECTURE.md\n          git diff --staged --quiet || git commit -m \"docs: refresh onboarding docs\"\n          git push\n```\n\n---\n\n## What gets generated\n\n### `CLAUDE.md`\n\nThe project brief that Claude Code and other AI tools read at the start of every session. Generated sections:\n\n| Section | What's in it |\n|---|---|\n| **Project Overview** | What the project does, who it's for, and its current state |\n| **Tech Stack** | Languages, frameworks, key libraries, infrastructure |\n| **Project Structure** | What each top-level directory contains and why |\n| **Key Commands** | Install, dev, build, test, lint — everything you need to get running |\n| **Architecture Overview** | The 3-paragraph mental model: what exists, how it connects, how data flows |\n| **Coding Conventions** | Naming patterns, file organization, patterns found in the actual code |\n| **Important Files** | Entry points, config files, the 10 files that matter most |\n| **Gotchas & Notes** | Non-obvious behaviors, known quirks, things that trip up new contributors |\n\nExample output:\n\n```markdown\n# Project Overview\nExpress is a minimal and flexible Node.js web application framework that provides\na robust set of features for web and mobile applications...\n\n# Key Commands\n\\`\\`\\`bash\nnpm install        # Install dependencies\nnpm test           # Run test suite (mocha)\nnpm run lint       # ESLint\n\\`\\`\\`\n\n# Gotchas & Notes\n- Middleware order matters — error-handling middleware must have 4 arguments (err, req, res, next)\n- `app.use()` vs `router.use()` have different mounting semantics\n- The `trust proxy` setting must be configured when running behind a load balancer\n```\n\n### `ARCHITECTURE.md`\n\nA technical deep-dive for engineers who need to understand the system. Generated sections:\n\n| Section | What's in it |\n|---|---|\n| **Architecture Overview** | High-level explanation of how the system is structured and why |\n| **Component Diagram** | ASCII or Mermaid diagram of major components and their relationships |\n| **Data Flow** | Step-by-step walkthrough of the primary use case end-to-end |\n| **Key Modules** | What each major module does, its public interface, and its dependencies |\n| **External Dependencies** | External services, APIs, databases this project depends on |\n| **Design Decisions** | Key architectural choices and the reasoning behind them |\n\n---\n\n## Options\n\n| Flag | Default | Description |\n|---|---|---|\n| `--output-dir <path>` | `.` | Directory to write generated files |\n| `--dry-run` | `false` | Print to stdout, don't write files |\n| `--no-architecture` | `false` | Skip generating `ARCHITECTURE.md` |\n| `--github-token <token>` | `$GITHUB_TOKEN` | Token for private repos or to raise API rate limits |\n| `-h, --help` | | Show help |\n| `-V, --version` | | Show version number |\n\n### Environment variables\n\n| Variable | Description |\n|---|---|\n| `ANTHROPIC_API_KEY` | **Required.** Your Anthropic API key |\n| `GITHUB_TOKEN` | Optional. GitHub personal access token. Raises rate limit from 60 to 5,000 req/hr |\n\n---\n\n## How it works\n\n```\nInput (GitHub URL or local path)\n  ↓\nRead repository\n  - GitHub repos: fetched via GitHub REST API (no cloning needed)\n  - Local repos:  walks filesystem, reads git log\n  - Prioritizes: package.json, README, CLAUDE.md, entry points, config files\n  - Applies token budget: reads up to ~80,000 chars of source code\n  ↓\nBuild context\n  - Directory tree\n  - File contents (prioritized by importance)\n  - Recent git commits\n  - Language/framework detection\n  ↓\nCall Claude\n  - Two separate prompts: one for CLAUDE.md, one for ARCHITECTURE.md\n  - Model: claude-opus-4-5\n  - Structured output with exact sections\n  ↓\nWrite output\n  - Writes to --output-dir (default: current directory)\n  - Existing files are overwritten (no merge — regenerate cleanly)\n```\n\n### File prioritization\n\nWhen a repo is too large to fit in one context window, `claude-onboard` prioritizes files in this order:\n\n1. `package.json`, `README.md`, `CLAUDE.md`, `Makefile`, `Dockerfile`\n2. Top-level source files\n3. Source files by directory depth (shallower = more important)\n4. Skipped entirely: `node_modules`, `dist`, `build`, `.git`, binary files, files over 100KB\n\n---\n\n## Supported languages & stacks\n\nWorks on any codebase. Especially well-tested on:\n\n- **JavaScript / TypeScript** (Node.js, React, Next.js, Express, NestJS)\n- **Python** (FastAPI, Django, Flask, data science)\n- **Go** (standard library, Gin, Echo)\n- **Rust** (Cargo projects)\n- **Ruby** (Rails, Sinatra)\n- **Java / Kotlin** (Spring Boot, Android)\n\n---\n\n## Cost estimate\n\nGenerating both documents on a typical medium-sized repo (~50 files) costs approximately **$0.05–0.15** in Claude API credits.\n\n---\n\n## Troubleshooting\n\n**Rate limit errors from GitHub**\n\n```bash\n# Add a GitHub token to get 5,000 requests/hour instead of 60\nnpx @amritessh/claude-onboard https://github.com/owner/repo --github-token $(gh auth token)\n```\n\n**ANTHROPIC_API_KEY not found**\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\n# Or add it to .env in your current directory\n```\n\n**Output is too generic / not accurate**\n\nThis usually means the repo is large and only a sample was read. Try running on a specific subdirectory, or use `--dry-run` to inspect what was generated.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/amritessh/claude-onboard\ncd claude-onboard\nnpm install\nnpm run dev        # watch mode\nnode dist/index.js . --dry-run   # test on this repo\n```\n\nPlease open an issue before starting significant work. PRs welcome.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-3a1eb3dbc57866be226412b663d26037"}