CodeNarrator - Understand Any Codebase Instantly

An AI-powered CLI & Web tool that automatically explains codebases in plain English.

---

Vision

CodeNarrator aims to bridge the gap between complex code and developer understanding. Whether you're a beginner exploring a new open-source repo, a maintainer reviewing a PR, or an engineer returning to your own old code — CodeNarrator helps you understand any codebase faster and with less effort.

We believe every developer deserves a tool that makes codebases more readable and approachable.

---

Key Features

• Explain entire codebases using AI
• CLI tool for use in terminal
• Recursive file scanner for JavaScript, TypeScript, Python, and more
• Outputs structured Markdown documentation
• Powered by Gemini or GPT-based AI models
• Planned GitHub PR integration to summarize changes

---

Tech Stack

Layer	Technologies Used
CLI Tool	Node.js, Commander.js, Chalk
AI Integration	Gemini API (via Google SDK)
File Scanning	fs, glob
Markdown Generation	Markdown, fs-extra
Web UI (Planned)	React.js, Tailwind CSS
Automation (Planned)	GitHub Actions, Pre-push Hooks

---

Project Structure

CodeNarrator/
|-- bin/
|   `-- cli.js                # CLI entry point
|-- src/
|   |-- analyzer.js           # Scans code and sends to AI (with file size limits)
|   |-- aiEngine.js           # Lazy-loads Gemini client when needed
|   `-- writer.js             # Saves generated Markdown
|-- test-models.js            # Test script (skips gracefully if no API key)
|-- .codenarratorrc.json      # Optional config
|-- .env                      # Your Gemini API key (if using dotenv method)
|-- README.md
`-- package.json

---

Getting Started (CLI)

1. Clone the repository

git clone https://github.com/your-username/CodeNarrator.git
cd CodeNarrator

2. Install dependencies

npm install

3. Add Gemini API Key (Required)

Option A: Export in your shell environment (recommended, especially for global installs):

export GEMINI_API_KEY=your-key

Option B: Create a .env file in the project root:

echo "GEMINI_API_KEY=your-key" > .env

Option C: Run commands with inline environment variable:

GEMINI_API_KEY=your-key codenarrator ./src --output ./docs

For testing:

# Test API connectivity
GEMINI_API_KEY=your-key npm test

# Or with dotenv preload
node -r dotenv/config test-models.js

4. Link CLI globally

npm link

5. Run on any codebase

codenarrator ./src --output ./docs --model=gemini

---

Sample Output

A sample generated file (docs/utils-logger.md) might look like this:

File: utils/logger.js

Overview:
This file provides logging utilities for the application.

Functions:
- logInfo(msg): Logs informational messages
- logError(err): Logs errors with stack trace

Notes:
Uses 'chalk' for styled terminal output.

---

Use Cases

• Understand unfamiliar open-source projects
• Speed up PR reviews with inline documentation
• Assist students in grasping legacy or complex code
• Help new team members onboard quickly

---

Roadmap

Version	Feature
1.0	CLI with basic AI documentation output
1.1	GitHub PR summarizer integration (planned)
1.2	Multi-language support: JS, Python, etc. (planned)
1.3	Web UI for drag-and-drop code analysis (planned)
2.0	VS Code extension with inline explanations
2.1	Team dashboard, history, authentication (planned)

---

Security Note

• Your code is sent to Gemini servers for analysis unless self-hosted.
• Avoid analyzing confidential or proprietary files.
• Configuration files like .env are excluded from analysis.
• Files larger than 200KB are automatically skipped to avoid excessive token usage.

---

Contributing

We welcome contributions from all developers.

• Open issues and feature suggestions
• Participate in GitHub Discussions
• Look for good first issue tags to get started

git checkout -b your-feature-branch
npm run dev
git commit -m "Add: your feature"

---

License

CodeNarrator is licensed under the MIT License. You are free to use, modify, and distribute it.