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**— Runcodeglance --for-ai
to generate a structured context brief instead of dumping the whole codebaseOnboarding 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.
## 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 →
| 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. SeeContributingto 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.,
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
MIT — see LICENSE.