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 MarkdownNo 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-aito generate a structured context brief instead of dumping the whole codebase - Onboarding your team —
codeglance --markdown > docs/codebase-tour.mdcreates 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 # Linuxnpx codeglance # zero install, works immediately
npm install -g codeglance # install globallycodeglance [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.mdCheck it in. Regenerate when the architecture changes. See the generated output for this repo →
| 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.phpfiles are counted in language stats, but manifest files (pom.xml, Gemfile, composer.json) are not parsed and no framework names are detected. See 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:
// 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
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.,
uvicornfor 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
MIT — see LICENSE.