I built a CLI that orients you in an unfamiliar repo: feedback wanted

A developer has released Codeglance, a CLI tool that provides a structured overview of any codebase without requiring installation, configuration, or API keys. The tool answers five key questions about a repository—what it is, how to run it, where to start, what tools it uses, and how to hand it off to an LLM—by reading manifest files and file structure.

npx codeglance No install. No config. No API keys. npx codeglance tour of current directory npx codeglance --for-ai compact LLM context brief npx codeglance --markdown --output docs/codebase-tour.md save as Markdown No install required. Runs on any directory. Works best on repos with common manifest files. Joining a new codebase — Skip the 15-minute ritual of reading README, exploring directories, and parsing package.json manually Evaluating a dependency — Understand what a library actually uses before you adopt it Returning to an old project — Re-orient yourself after months away Before using Claude, Cursor, or Copilot — Run codeglance --for-ai to generate a structured context brief instead of dumping the whole codebase Onboarding your team — codeglance --markdown docs/codebase-tour.md creates a living onboarding document Not a line counter. tokei and scc count lines of code. They don't tell you what framework you're looking at or how to run it. Not a source-code dumper. repomix and code2prompt pack source for LLM consumption. codeglance produces a context brief — just the orientation layer. Not an AI agent. No generation, no inference, no API calls. It reads manifest files and file structure, then reports what it finds. A repo orientation layer. It answers five questions in one command: what is this, how do I run it, where do I start, what tools does it use, and how do I hand it off to an LLM. All outputs below were captured by running codeglance against the actual repos. codeglance glow · Go charmbracelet/glow ── WHAT IS THIS ────────────────────────────────────────────────────── CLI tool Go using Cobra Runtime Go 1.25.9 Other Viper 1.21.0 ── HOW TO RUN IT ───────────────────────────────────────────────────── go run . run main package go build ./... compile all packages go test ./... run test suite go vet ./... run static analysis ── WHERE TO START ──────────────────────────────────────────────────── main.go main package Dockerfile container definition config cmd.go cmd configuration github.go GitHub integration gitlab.go GitLab integration url.go URL parsing ui/markdown.go Markdown renderer ── TOOLS DETECTED ──────────────────────────────────────────────────── CI/CD GitHub Actions 6 workflows Container Docker Linting golangci-lint ── CODEBASE ────────────────────────────────────────────────────────── Go 25 files 3.6k lines ███████████████░░░ 86% 45 files · 4.2k lines · 4 languages codeglance express · Node.js expressjs/express ── WHAT IS THIS ────────────────────────────────────────────────────── Node.js project — ESLint Runtime Node.js = 18 Pkg manager npm Linting ESLint 8 ── HOW TO RUN IT ───────────────────────────────────────────────────── npm run test run test suite npm run lint lint codebase ── WHERE TO START ──────────────────────────────────────────────────── lib/express.js express lib/utils.js utilities lib/view.js view/template layer lib/application.js app bootstrap lib/request.js request object lib/response.js response object ── TOOLS DETECTED ──────────────────────────────────────────────────── Testing test/ CI/CD GitHub Actions 4 workflows Linting ESLint ── CODEBASE ────────────────────────────────────────────────────────── JavaScript 141 files 21k lines ███████████████░░░ 82% 213 files · 26k lines · 6 languages codeglance flask · Python pallets/flask ── WHAT IS THIS ────────────────────────────────────────────────────── CLI tool Python using Click Runtime Python =3.10 ── HOW TO RUN IT ───────────────────────────────────────────────────── pytest run test suite ruff check . lint with Ruff ── WHERE TO START ──────────────────────────────────────────────────── src/flask/app.py flask entry src/flask/blueprints.py route blueprints src/flask/config.py configuration src/flask/globals.py global request context src/flask/logging.py logging setup src/flask/sessions.py session management ── TOOLS DETECTED ──────────────────────────────────────────────────── Testing tests/ CI/CD GitHub Actions 5 workflows Linting Ruff · mypy ── CODEBASE ────────────────────────────────────────────────────────── Python 83 files 18k lines ██████████░░░░░░░░ 53% 233 files · 35k lines · 10 languages Run codeglance --for-ai to get a compact, structured LLM context brief. Paste it into Claude, GPT, or Gemini before asking about the codebase. Typically under 300 tokens. No source code. Codebase Context: my-saas-app Stack Next.js 14 with Prisma, tRPC Runtime: Node.js =18 · Package manager: pnpm Commands - dev: pnpm dev - build: pnpm build - test: pnpm test - lint: pnpm lint Key Files - next.config.ts — Next.js config - prisma/schema.prisma — Prisma data model - src/server/routers/app.ts — tRPC router - src/lib/db.ts — database client Libraries Prisma, Auth.js, tRPC, Vitest, Playwright Infrastructure GitHub Actions 1 workflows · docker-compose --- Generated by codeglance. Heuristic — not exhaustive. codeglance --for-ai | pbcopy macOS codeglance --for-ai | xclip Linux npx codeglance zero install, works immediately npm install -g codeglance install globally codeglance path analyze current dir or a path codeglance --for-ai compact LLM context brief codeglance --markdown Markdown report codeglance --json machine-readable output codeglance --output docs/tour.md save to file codeglance --no-git skip git analysis faster on large repos codeglance --markdown --output docs/codebase-tour.md Check it in. Regenerate when the architecture changes. See the generated output for this repo → /mansoor-mamnoon/codeglance/blob/main/docs/codebase-tour.md | Ecosystem | Manifest | What gets detected | |---|---|---| Node.js | package.json | Next.js, React, Vue, Angular, Svelte, Express, NestJS, Fastify, Prisma, Drizzle, tRPC, GraphQL, Vitest, Jest, Playwright, ESLint, Tailwind — 50+ packages | Python | pyproject.toml , requirements.txt | FastAPI, Django, Flask, SQLAlchemy, Pydantic, Pytest, Ruff, Black, PyTorch, LangChain, Anthropic SDK | Go | go.mod | Gin, Echo, Fiber, Chi, GORM, Cobra, gRPC, Zap | Rust | Cargo.toml | Axum, Actix-web, Rocket, Tokio, SQLx, Clap, Serde, Tracing | C/C++ | CMakeLists.txt | GoogleTest, Catch2, Boost, Qt, OpenCV; CMake version and C++ standard | Use the right tool for the job: tokei / scc — accurate LOC counts by language. Best when you need raw code size data. repomix / code2prompt — pack source code into a file for LLM consumption. Best when you need to feed a full codebase to a model. codeglance — repo orientation. Best when you need to understand a repo before you start working with it. | codeglance | tokei/scc | repomix | | |---|---|---|---| | Framework detection | ✓ | ✗ | ✗ | | Run/build/test commands | ✓ | ✗ | ✗ | | Entry points | ✓ | ✗ | ✗ | | "Files to read first" | ✓ | ✗ | ✗ | | CI / Docker / tooling | ✓ | ✗ | ✗ | | Language stats | ✓ | ✓ | ✗ | | LLM context brief | ✓ | ✗ | ✓ full source | | Zero config | ✓ | ✓ | ✓ | codeglance is transparent about what it is and what it is not: Heuristic, not semantic. It reads manifest files and file structure. It does not parse source code or understand logic. Framework detection depends on manifests. Projects without a standard package file go.mod, package.json, Cargo.toml, pyproject.toml, CMakeLists.txt produce shallow output. Mixed-ecosystem repos a Python backend + Node.js frontend are analyzed from the first detected ecosystem. The other ecosystem's files still appear in language stats and WHERE TO START. Library repos that are a framework themselves e.g., fastapi, gin-gonic/gin show their own dependencies, not their framework name. Java, Ruby, and PHP are not yet supported. .java , .rb , and .php files are counted in language stats, but manifest files pom.xml, Gemfile, composer.json are not parsed and no framework names are detected. See Contributing contributing to add support. Monorepos get a single summary, not per-package analysis. Large repos are capped at 25,000 files. A note appears in the output. "Start here" ranking is approximate. Based on file depth, naming patterns, and size — not import graph analysis. Each ecosystem detector is a self-contained module. Adding a framework takes ~3 lines: js // src/detectors/frameworks.ts — add to the relevant array: const NODE FRAMEWORKS: FrameworkDef = // ... { name: 'My Framework', category: 'web framework', keys: 'my-framework-package' }, ; Add a fixture + test, run npm test , submit a PR. Full guide: CONTRIBUTING.md /mansoor-mamnoon/codeglance/blob/main/CONTRIBUTING.md Open contributions: - Java/Spring Boot detector pom.xml, build.gradle - Ruby/Rails detector Gemfile - PHP/Laravel/Symfony detector composer.json - Elixir/Phoenix detector mix.exs - pnpm workspace monorepo detection - Python dev server command inference e.g., uvicorn for FastAPI - Improve Rust "start here" ranking with workspace support v0.2 — Java/Kotlin, monorepo support, --since diff mode v0.3 — GitHub Action, Homebrew tap Future — VS Code extension, --watch mode, plugin system Full roadmap: ROADMAP.md /mansoor-mamnoon/codeglance/blob/main/ROADMAP.md MIT — see LICENSE /mansoor-mamnoon/codeglance/blob/main/LICENSE .