frumle

AI-powered codebase analyzer that automatically generates comprehensive documentation and insights about your codebase using AI.

✨ What is frumle?

frumle scans your codebase, analyzes it with AI, and generates detailed documentation including:

• API Documentation: Automatically detects and documents all endpoints, their relationships, and authentication flows
• Structured Analysis: Organized documentation with overview, architecture, tech stack, and key features
• Code Optimization Insights: Actionable recommendations to improve performance, reduce latency, and enhance code quality
• Project Organization: Clear ownership tracking with project names for easy management

All documentation is securely stored in your dashboard where you can access it anytime.

🚀 Quick Start

Step 1: Install

npm install --save-dev frumle

Then run via:

npx frumle ./src

Note: Avoid npm install -g frumle if you also use Frumle for Python, C#, or PHP — global installs from different package managers can conflict. Use npx instead.

Step 2: Get Your API Key

1. Visit frumle.com
2. Sign up for a free account
3. Navigate to your dashboard
4. Copy your API key

Step 3: Add Your API Key

npx frumle add-key <your-api-key>

Or use the login alias:

npx frumle login <your-api-key>

Or set an environment variable (useful for CI — no add-key needed):

export FRUMLE_API_KEY=frumle_…
npx frumle

FRUMLE_API_KEY overrides the key stored in ~/.frumle/config.json.

You'll see a confirmation with your quota and usage information.

Step 4: Analyze Your Codebase

npx frumle

Or analyze a specific directory:

npx frumle ./src

That's it! Your analysis will be processed in the background and saved to your dashboard. The CLI will exit immediately after queuing the analysis.

Note: Running frumle without arguments analyzes the current directory, making it perfect for running from your project root.

📖 Usage

Basic Commands

Analyze current directory:

npx frumle

Analyze a specific directory:

npx frumle ./src

Check your account status and quota:

npx frumle status

Add or update your API key:

npx frumle add-key <your-api-key>

Options

Specify a custom project name:

npx frumle ./src --project-name "my-awesome-project"

Ignore specific directories:

npx frumle ./src --ignore node_modules,dist,tests,.next

CI / unattended (env key, no local config write, JSON output):

export FRUMLE_API_KEY=frumle_…
npx frumle . --project-name "my-api" --skip-config-write --json

When CI=true (GitHub Actions sets this), Frumle skips writing frumle.config.json automatically.

Auto-docs on every push (GitHub Action):

1. Run npx frumle once — when asked, choose Y to add .github/workflows/frumle.yml
   (or run npx frumle ci anytime)
2. Set the secret:

gh secret set FRUMLE_API_KEY

3. Commit and push the workflow file

After that, every push to main/master queues a fresh analysis. Docs show up in your dashboard.
A green Actions run means the scan was queued — not that docs finished instantly.

If you choose n at the prompt, you’ll need to run npx frumle yourself whenever docs should update.

Share docs with frontend AI agents (MCP)

After your project is documented on frumle.com, create a read key (POST /api/v1/projects/:projectName/read-keys with your frumle_… key). It cannot analyze or spend analyze credits. Share the frk_… value with frontend engineers.

Frontend (in Cursor / Claude Code / etc.):

npx @frumle/mcp init --key frk_…

Agents can then list_endpoints / search_endpoints / get_endpoint against live Frumle docs. See @frumle/mcp / mcp-package/README.md.

Default behavior:

• Project name is automatically extracted from package.json (if present) or the directory name
• Default ignored directories: node_modules, .git, dist, build, .next
• Auth: FRUMLE_API_KEY env, else ~/.frumle/config.json from add-key

Exit codes

| Code | Meaning | |------|---------| | 0 | Analysis queued or completed | | 1 | Client / unexpected error (bad path, no files, etc.) | | 2 | Auth failure (missing or invalid API key) | | 3 | Quota or payment required |

Environment variables

| Variable | Purpose | |----------|---------| | FRUMLE_API_KEY | API key (overrides config file) | | FRUMLE_API_URL | Override API base URL (default: production) | | CI | When true/1, skip writing frumle.config.json |

📋 Examples

Analyze current directory (most common)

npx frumle

This analyzes the current directory - perfect when you're in your project root!

Analyze a specific directory

npx frumle ./src
npx frumle ./backend

Analyze with custom project name

npx frumle --project-name "api-backend"
npx frumle ./src --project-name "api-backend"

Exclude test files and build directories

npx frumle --ignore tests,coverage,build,.next
npx frumle ./src --ignore tests,coverage,build,.next

🎯 Features

• 🔍 Smart Detection: Automatically identifies APIs, endpoints, and their relationships
• ⚡ Background Processing: Analysis runs asynchronously - no waiting for completion
• 📊 Structured Documentation: Organized into separate fields (overview, architecture, APIs, tech stack)
• 🎯 Optimization Insights: Actionable recommendations for performance, latency, and code quality
• 📦 Project Organization: Clear project naming and ownership tracking
• 🔒 Secure: Your code is processed securely and stored in your private dashboard
• 🚀 No Configuration: Works out of the box with sensible defaults

💡 What You'll Get

After running an analysis, you'll have access to:

Structured Documentation

• Overview: Brief project description
• Architecture: Detailed system architecture and design patterns
• Tech Stack: Complete list of frameworks, libraries, and tools used
• API Endpoints: Comprehensive list of all endpoints with methods, paths, descriptions, and authentication requirements
• Key Features: List of main functionality and capabilities
• Dependencies: Core package dependencies

API Documentation

• Every endpoint with HTTP methods and paths
• Authentication and authorization requirements
• API relationships and dependencies
• Data flows between endpoints

Code Optimization Insights

• Performance Bottlenecks: Identifies N+1 queries, missing indexes, inefficient algorithms
• API Latency Improvements: Caching strategies, query optimizations, response compression suggestions
• Code Quality Enhancements: Code smells, refactoring opportunities, security improvements
• Architecture Improvements: Better patterns, scalability suggestions, maintainability enhancements

Project Summary

• High-level overview of your architecture and tech stack
• Complete API endpoint catalog
• Authentication flows and patterns
• File-by-file analysis documentation

All documentation is accessible through your dashboard at frumle.com.

🔄 How It Works

1. Queue Analysis: CLI sends your codebase to the backend and receives immediate confirmation
2. Background Processing: Analysis runs asynchronously on the server (no timeout issues)
3. AI Analysis: Files are analyzed for APIs, architecture, and code patterns
4. Structured Extraction: Documentation is organized into structured fields
5. Storage: Results are saved to your dashboard with clear project ownership
6. Access: View comprehensive documentation anytime in your dashboard

❓ Troubleshooting

No API key found?

export FRUMLE_API_KEY=frumle_…   # CI / scripts
# or
npx frumle add-key <your-api-key>

Check your quota and usage:

npx frumle status

Project name not detected?

npx frumle ./src --project-name "my-project"

Need help? Visit frumle.com for support and documentation.

📄 License

MIT