explainthisrepo 0.9.0 → 0.9.2

package/README.md

@@ -1,10 +1,8 @@
 # ExplainThisRepo
 
-ExplainThisRepo is a CLI that generates plain-English explanations of any codebase (GitHub repositories and local directories) by analyzing project structure, READMEs, and high signal files.
+_The fastest way to understand any codebase in plain English using real project signals. Not blind AI summarization._
 
-ExplainThisRepo is a command-line tool that analyzes GitHub repositories and local directories to generate plain-English explanations of the codebase architecture.
-
-It helps developers quickly understand unfamiliar codebases by deriving architectural explanations from real project structure and code signals, producing a clear, structured `EXPLAIN.md`.
+ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests, dependencies graph, file structure and high-signal files producing a clear, structured `EXPLAIN.md` that explains what the codebase does and how it is organized in plain English.
 
 [![PyPI Version](https://img.shields.io/pypi/v/explainthisrepo?color=blue)](https://pypi.org/project/explainthisrepo/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/explainthisrepo?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/explainthisrepo)
@@ -14,45 +12,99 @@ It helps developers quickly understand unfamiliar codebases by deriving architec
 [![Node](https://img.shields.io/node/v/explainthisrepo)](https://www.npmjs.com/package/explainthisrepo)
 [![Docs](https://img.shields.io/badge/docs-explainthisrepo.com-black)](https://explainthisrepo.com)
 
----
-
 ![demo](https://github.com/user-attachments/assets/837e0593-db64-4657-8855-bb1915011eb6)
----
 
 ## Key Features
 
-- Generates architectural summaries from repository structure and code signals
-- Fetches public repositories by GitHub URLs (with or without https), `owner/repo` format, issue links, query strings, and SSH clone links
-- Analyzes repository data including file tree, configs, entrypoints, and high signal source files
-- Extracts repo signals from key files (package.json, pyproject.toml, config files, entrypoints)
-- Builds a file tree summary to understand project architecture
-- Detects programming languages with the GitHub API
-- Analyzes local project directories using the same pipeline as GitHub repositories
-- Generates a structured plain-English explanation grounded in actual project files
+- Understand any GitHub repository in seconds
+- Derives architectural summaries from repository structure and code signals.
+Not blind AI summarization.
+- Translates complex code structures into plain English
+- Extract architecture signals from configs, entrypoints, and manifests
+- Works with GitHub repositories, local directories, private repositories, and monorepos
 - Outputs the explanation to an `EXPLAIN.md` file in your current directory or prints it directly in the terminal
-- Multi-mode command-line interface
+- Multiple explanation modes (quick, simple, detailed)
 
----
+## Installation
 
-## Modes
+### Option 1: install with pip (recommended):
 
-- (no flag) → Full repository explanation written to EXPLAIN.md
+Requirements: Python 3.9+
 
-- `--quick` → One-sentence summary
+```bash
+pip install explainthisrepo
+explainthisrepo owner/repo
 
-- `--simple` → Short, simplified explanation
+# pip install explainthisrepo
+# explainthisrepo .
+```
 
-- `--detailed` → Deeper explanation including structure and architecture
+Alternatively,
 
-- `--stack` → Tech stack breakdown from repo signals
+```bash
+pipx install explainthisrepo
+explainthisrepo owner/repo
+```
 
-- `--version` → Check installed CLI version
+To install support for specific models:
 
-- `--help` → Show usage guide
+```bash
+pip install explainthisrepo[gemini]
+pip install explainthisrepo[openai]
+pip install explainthisrepo[anthropic]
+pip install explainthisrepo[groq]
+```
 
-- `--doctor` → Check system health and active model diagnostics
+### Option 2: Install with npm
 
----
+Install globally and use forever:
+
+```bash
+npm install -g explainthisrepo
+explainthisrepo owner/repo
+
+# npm install -g explainthisrepo
+# explainthisrepo .
+```
+
+Or without install:
+
+```bash
+npx explainthisrepo owner/repo
+```
+
+Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`).
+
+### Option 3: Download standalone binary
+
+Prebuilt standalone binaries are available for macOS, Linux, and Windows.
+
+> Standalone binaries require no Python or Node installation and run as a single executable.
+
+Download the latest release:
+
+[github.com/calchiwo/ExplainThisRepo/releases/latest](https://github.com/calchiwo/ExplainThisRepo/releases/latest)
+
+Or install directly:
+
+macOS
+
+```bash
+curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-darwin-arm64 -o explainthisrepo
+chmod +x explainthisrepo
+```
+
+Linux
+```bash
+curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-linux-x64 -o explainthisrepo
+chmod +x explainthisrepo
+```
+
+Windows (PowerShell)
+
+```powershell
+curl -L https://github.com/calchiwo/ExplainThisRepo/releases/latest/download/explainthisrepo-win-x64.exe -o explainthisrepo.exe
+```
 
 ## Configuration
 
@@ -61,8 +113,9 @@ ExplainThisRepo supports multiple LLM models:
 - Gemini
 - OpenAI
 - Ollama (local or cloud-routed)
-
-### Quick setup (recommended)
+- Anthropic
+- Groq
+- OpenRouter
 
 Use the built-in `init` command to configure your preferred model:
 
@@ -70,49 +123,35 @@ Use the built-in `init` command to configure your preferred model:
 explainthisrepo init
 # or npx explainthisrepo init
 ```
+
 > For details about how initialization works, see [INIT.md](INIT.md).
 
-## Installation
 
-### Option 1: install with pip (recommended):
+## Flag options
 
-Requirements: Python 3.9+
+- (no flag) → Full repository explanation written to `EXPLAIN.md`
 
-```bash
-pip install explainthisrepo
-explainthisrepo owner/repo
-```
+- `--quick` → One-sentence summary
 
-Alternatively,
+- `--simple` → Short, simplified explanation
 
-```bash
-pipx install explainthisrepo
-explainthisrepo owner/repo
-```
+- `--detailed` → Deeper explanation including structure and architecture
 
-To install support for specific models:
+- `--stack` → Tech stack breakdown from repo signals
 
-```bash
-pip install explainthisrepo[gemini]
-pip install explainthisrepo[openai]
-```
+- `--version` → Check installed CLI version
 
-### Option 2: Install with npm
+- `--help` → Show usage guide
 
-Install globally and use forever:
-```bash
-npm install -g explainthisrepo
-explainthisrepo owner/repo
-# or: npx explainthisrepo owner/repo
-```
+- `--doctor` → Check system health and active model diagnostics
 
-Replace `owner/repo` with the GitHub repository identifier (e.g., `facebook/react`).
+- `--llm` → Override provider selection
 
----
+- `--token/-t` → Set GitHub token for private repositories and to avoid rate limits
 
 ## Flexible Repository and Local Directory Input
 
-Accepts various formats for repository input, full GitHub URLs, issue links, and SSH clone links.
+Accepts various formats for repository input, full GitHub URLs (with or without https), `owner/repo` format, issue links, query strings, and SSH clone links
 
 ```bash
 explainthisrepo https://github.com/owner/repo
@@ -126,45 +165,47 @@ explainthisrepo ./path/to/directory
 
 All inputs are normalized internally to `owner/repo`.
 
----
-
 ## Model selection
 
-The `--llm` flag to selects which configured model backend to use for the current command
+The `--llm` flag selects which configured model backend to use for the current command.
 
 ```bash
 explainthisrepo owner/repo --llm gemini
 explainthisrepo owner/repo --llm openai
 explainthisrepo owner/repo --llm ollama
+explainthisrepo owner/repo --llm anthropic
+explainthisrepo owner/repo --llm openrouter
+explainthisrepo owner/repo --llm groq
 ```
 
 `--llm` works with all modes (``--quick``, ``--simple``, ``--detailed``).
 
-## Usage
+## Command line usage
 
-### Basic
+### Default
 Writes a full explanation to `EXPLAIN.md`:
 
 ```bash
 explainthisrepo owner/repo
+#e.g. explainthisrepo vercel/next.js
 ```
-Example:
-```bash
-explainthisrepo facebook/react
-```
----
 
 ### Quick mode
 
 Prints a one-sentence summary to stdout:
-
 ```bash
 explainthisrepo owner/repo --quick
+# explainthisrepo facebook/react --quick
 ```
-Example:
+
 ```bash
-explainthisrepo facebook/react --quick
+$ explainthisrepo vercel/next.js --quick
+
+Next.js is a React framework that provides server-side rendering,
+file-based routing, API routes, and build tooling for fullstack
+web applications.
 ```
+
 ![Quick Mode Output](assets/quick-command-output.png)
 
 ---
@@ -222,42 +263,41 @@ explainthisrepo . --stack
 
 When analyzing a local directory:
 - Repository structure is derived from the filesystem
-- High signal files (Configs, README, entrypoints) are extracted locally
+- High signal files (configs, entrypoints, manifests) are extracted locally
 - No GitHub APIs calls are made
 - All prompts and outputs remain identical
 
 This allows analysis of projects directly from the local filesystem, without requiring a GitHub repository.
 
-### Version
+### For private repositories, use the --token/-t option.
 
-Print the installed CLI version:
+Setting a `GITHUB_TOKEN` environment variable is recommended to avoid rate limits when analyzing public repositories.
 
 ```bash
-explainthisrepo --version
+export GITHUB_TOKEN=yourActualTokenHere
 ```
 
----
+### Version
 
-### Diagnostics
-Use the `--doctor` flag to verify the environment, network connectivity, and API key configuration:
+Check the installed CLI version:
 
 ```bash
-explainthisrepo --doctor
+explainthisrepo --version
 ```
 
-### Set GitHub Token
+### Diagnostics
 
-Setting a `GITHUB_TOKEN` environment variable is recommended to avoid rate limits when analyzing public repositories.
+Use the `--doctor` flag to verify the environment, network connectivity, and API key configuration:
 
 ```bash
-export GITHUB_TOKEN=yourActualTokenHere
+explainthisrepo --doctor
 ```
 
 ## Termux (Android) install notes
 
 Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`.
 
-### Recommended install (Termux)
+However, it's recommended you install using:
 
 ```bash
 pip install --user -U explainthisrepo
@@ -269,7 +309,7 @@ Make sure your user bin directory is on your PATH:
 export PATH="$HOME/.local/bin:$PATH"
 ```
 
-> Tip: Add the PATH export to your ~/.bashrc or ~/.zshrc so it persists.
+> Tip: Add the PATH export to your `~/.bashrc` or `~/.zshrc` so it persists.
 
 ### Alternative (No PATH changes)
 
@@ -287,6 +327,18 @@ Installing Gemini support may require building Rust-based dependencies on Androi
 pip install --user -U "explainthisrepo[gemini]"
 ```
 
+For mobile environments like Termux where compiling Python dependencies can be slow,
+you can also run ExplainThisRepo using the Node.js version:
+
+```bash
+npx explainthisrepo owner/repo
+```
+
+## Special Thanks
+
+- @Spectra010s for implementing the Node.js version of ExplainThisRepo and improving installation support for mobile environments like Termux
+- @HalxDocs for implementing the `--detailed` mode for deeper architectural explanations
+
 ## Contributions
 
 Contributions are welcome!
@@ -296,14 +348,10 @@ If you find a bug, have an idea, or want to improve the tool:
 - Open an issue for bugs/feature requests
 - Or submit a pull request for fixes/improvements
 
----
-
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
 
----
-
 ## Author
 
 Caleb Wodi

package/dist/config.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import toml from "toml";
+import { parse } from "@iarna/toml";
 const CONFIG_DIR_NAME = "ExplainThisRepo";
 const CONFIG_FILE_NAME = "config.toml";
 export function getConfigPath() {
@@ -38,7 +38,7 @@ export function loadConfig() {
         return {};
     }
     try {
-        return toml.parse(raw);
+        return parse(raw);
     }
     catch (err) {
         throw new Error("Invalid config.toml format");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "explainthisrepo",
-  "version": "0.9.0",
-  "description": "CLI that generates plain-English explanations of any codebase",
+  "version": "0.9.2",
+  "description": "The fastest way to understand any codebase in plain English. Not blind AI summarization",
   "license": "MIT",
   "type": "module",
   "author": "Caleb Wodi <calebwodi33@gmail.com>",
@@ -27,7 +27,9 @@
     "developer-tools"
   ],
   "bin": {
-    "explainthisrepo": "dist/cli.js"
+    "explainthisrepo": "dist/cli.js",
+    "explain-this-repo": "dist/cli.js",
+    "etr": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -50,7 +52,8 @@
     "commander": "^14.0.3",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",
-    "ora": "^9.3.0"
+    "ora": "^9.3.0",
+    "toml": "^3.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",