{"slug": "i-built-a-cli-that-orients-you-in-an-unfamiliar-repo-feedback-wanted", "title": "I built a CLI that orients you in an unfamiliar repo: feedback wanted", "summary": "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.", "body_md": "\n\n```\nnpx codeglance\n```\n\nNo install. No config. No API keys.\n\n```\nnpx codeglance                                        # tour of current directory\nnpx codeglance --for-ai                               # compact LLM context brief\nnpx codeglance --markdown --output docs/codebase-tour.md  # save as Markdown\n```\n\nNo install required. Runs on any directory. Works best on repos with common manifest files.\n\n**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`\n\nto generate a structured context brief instead of dumping the whole codebase**Onboarding your team**—`codeglance --markdown > docs/codebase-tour.md`\n\ncreates a living onboarding document\n\n**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.\n\n**Not a source-code dumper.** repomix and code2prompt pack source for LLM consumption. codeglance produces a context *brief* — just the orientation layer.\n\n**Not an AI agent.** No generation, no inference, no API calls. It reads manifest files and file structure, then reports what it finds.\n\n**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.\n\nAll outputs below were captured by running codeglance against the actual repos.\n\n```\n  codeglance  glow · Go\n  charmbracelet/glow\n\n── WHAT IS THIS ──────────────────────────────────────────────────────\n  CLI tool (Go) using Cobra\n  Runtime     Go 1.25.9\n  Other        Viper 1.21.0\n\n── HOW TO RUN IT ─────────────────────────────────────────────────────\n  go run .         run main package\n  go build ./...   compile all packages\n  go test ./...    run test suite\n  go vet ./...     run static analysis\n\n── WHERE TO START ────────────────────────────────────────────────────\n  main.go           main package\n  Dockerfile        container definition\n  config_cmd.go     cmd configuration\n  github.go         GitHub integration\n  gitlab.go         GitLab integration\n  url.go            URL parsing\n  ui/markdown.go    Markdown renderer\n\n── TOOLS DETECTED ────────────────────────────────────────────────────\n  CI/CD        GitHub Actions (6 workflows)\n  Container    Docker\n  Linting      golangci-lint\n\n── CODEBASE ──────────────────────────────────────────────────────────\n  Go    25 files  3.6k lines  ███████████████░░░  86%\n  45 files  ·  4.2k lines  ·  4 languages\ncodeglance  express · Node.js\n  expressjs/express\n\n── WHAT IS THIS ──────────────────────────────────────────────────────\n  Node.js project — ESLint\n  Runtime     Node.js >= 18\n  Pkg manager npm\n  Linting      ESLint 8\n\n── HOW TO RUN IT ─────────────────────────────────────────────────────\n  npm run test       run test suite\n  npm run lint       lint codebase\n\n── WHERE TO START ────────────────────────────────────────────────────\n  lib/express.js       express\n  lib/utils.js         utilities\n  lib/view.js          view/template layer\n  lib/application.js   app bootstrap\n  lib/request.js       request object\n  lib/response.js      response object\n\n── TOOLS DETECTED ────────────────────────────────────────────────────\n  Testing      (test/)\n  CI/CD        GitHub Actions (4 workflows)\n  Linting      ESLint\n\n── CODEBASE ──────────────────────────────────────────────────────────\n  JavaScript    141 files  21k lines  ███████████████░░░  82%\n  213 files  ·  26k lines  ·  6 languages\ncodeglance  flask · Python\n  pallets/flask\n\n── WHAT IS THIS ──────────────────────────────────────────────────────\n  CLI tool (Python) using Click\n  Runtime     Python >=3.10\n\n── HOW TO RUN IT ─────────────────────────────────────────────────────\n  pytest         run test suite\n  ruff check .   lint with Ruff\n\n── WHERE TO START ────────────────────────────────────────────────────\n  src/flask/app.py            flask entry\n  src/flask/blueprints.py     route blueprints\n  src/flask/config.py         configuration\n  src/flask/globals.py        global request context\n  src/flask/logging.py        logging setup\n  src/flask/sessions.py       session management\n\n── TOOLS DETECTED ────────────────────────────────────────────────────\n  Testing      (tests/)\n  CI/CD        GitHub Actions (5 workflows)\n  Linting      Ruff  ·  mypy\n\n── CODEBASE ──────────────────────────────────────────────────────────\n  Python    83 files  18k lines  ██████████░░░░░░░░  53%\n  233 files  ·  35k lines  ·  10 languages\n```\n\nRun `codeglance --for-ai`\n\nto 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.\n\n```\n# Codebase Context: my-saas-app\n\n## Stack\nNext.js 14 with Prisma, tRPC\nRuntime: Node.js >=18 · Package manager: pnpm\n\n## Commands\n- **dev:** `pnpm dev`\n- **build:** `pnpm build`\n- **test:** `pnpm test`\n- **lint:** `pnpm lint`\n\n## Key Files\n- `next.config.ts` — Next.js config\n- `prisma/schema.prisma` — Prisma data model\n- `src/server/routers/app.ts` — tRPC router\n- `src/lib/db.ts` — database client\n\n## Libraries\nPrisma, Auth.js, tRPC, Vitest, Playwright\n\n## Infrastructure\nGitHub Actions (1 workflows) · docker-compose\n\n---\n*Generated by codeglance. Heuristic — not exhaustive.*\ncodeglance --for-ai | pbcopy    # macOS\ncodeglance --for-ai | xclip     # Linux\nnpx codeglance                        # zero install, works immediately\nnpm install -g codeglance             # install globally\ncodeglance [path]                     # analyze current dir or a path\ncodeglance --for-ai                   # compact LLM context brief\ncodeglance --markdown                 # Markdown report\ncodeglance --json                     # machine-readable output\ncodeglance --output docs/tour.md      # save to file\ncodeglance --no-git                   # skip git analysis (faster on large repos)\ncodeglance --markdown --output docs/codebase-tour.md\n```\n\nCheck it in. Regenerate when the architecture changes. [See the generated output for this repo →](/mansoor-mamnoon/codeglance/blob/main/docs/codebase-tour.md)\n\n| Ecosystem | Manifest | What gets detected |\n|---|---|---|\nNode.js |\n`package.json` |\nNext.js, React, Vue, Angular, Svelte, Express, NestJS, Fastify, Prisma, Drizzle, tRPC, GraphQL, Vitest, Jest, Playwright, ESLint, Tailwind — 50+ packages |\nPython |\n`pyproject.toml` , `requirements.txt` |\nFastAPI, Django, Flask, SQLAlchemy, Pydantic, Pytest, Ruff, Black, PyTorch, LangChain, Anthropic SDK |\nGo |\n`go.mod` |\nGin, Echo, Fiber, Chi, GORM, Cobra, gRPC, Zap |\nRust |\n`Cargo.toml` |\nAxum, Actix-web, Rocket, Tokio, SQLx, Clap, Serde, Tracing |\nC/C++ |\n`CMakeLists.txt` |\nGoogleTest, Catch2, Boost, Qt, OpenCV; CMake version and C++ standard |\n\nUse the right tool for the job:\n\n**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.\n\n| codeglance | tokei/scc | repomix | |\n|---|---|---|---|\n| Framework detection | ✓ | ✗ | ✗ |\n| Run/build/test commands | ✓ | ✗ | ✗ |\n| Entry points | ✓ | ✗ | ✗ |\n| \"Files to read first\" | ✓ | ✗ | ✗ |\n| CI / Docker / tooling | ✓ | ✗ | ✗ |\n| Language stats | ✓ | ✓ | ✗ |\n| LLM context brief | ✓ | ✗ | ✓ (full source) |\n| Zero config | ✓ | ✓ | ✓ |\n\ncodeglance is transparent about what it is and what it is not:\n\n**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`\n\n,`.rb`\n\n, and`.php`\n\nfiles 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.\n\nEach ecosystem detector is a self-contained module. **Adding a framework takes ~3 lines:**\n\n``` js\n// src/detectors/frameworks.ts — add to the relevant array:\nconst NODE_FRAMEWORKS: FrameworkDef[] = [\n  // ...\n  { name: 'My Framework', category: 'web_framework', keys: ['my-framework-package'] },\n];\n```\n\nAdd a fixture + test, run `npm test`\n\n, submit a PR. Full guide: [CONTRIBUTING.md](/mansoor-mamnoon/codeglance/blob/main/CONTRIBUTING.md)\n\n**Open contributions:**\n\n- Java/Spring Boot detector (pom.xml, build.gradle)\n- Ruby/Rails detector (Gemfile)\n- PHP/Laravel/Symfony detector (composer.json)\n- Elixir/Phoenix detector (mix.exs)\n- pnpm workspace monorepo detection\n- Python dev server command inference (e.g.,\n`uvicorn`\n\nfor FastAPI) - Improve Rust \"start here\" ranking with workspace support\n\n**v0.2** — Java/Kotlin, monorepo support, `--since`\n\ndiff mode\n\n**v0.3** — GitHub Action, Homebrew tap\n\n**Future** — VS Code extension, `--watch`\n\nmode, plugin system\n\nFull roadmap: [ROADMAP.md](/mansoor-mamnoon/codeglance/blob/main/ROADMAP.md)\n\nMIT — see [LICENSE](/mansoor-mamnoon/codeglance/blob/main/LICENSE).", "url": "https://wpnews.pro/news/i-built-a-cli-that-orients-you-in-an-unfamiliar-repo-feedback-wanted", "canonical_source": "https://github.com/mansoor-mamnoon/codeglance", "published_at": "2026-06-03 02:13:09+00:00", "updated_at": "2026-06-03 02:47:53.863203+00:00", "lang": "en", "topics": ["ai-tools"], "entities": ["codeglance", "Claude", "Cursor", "Copilot", "tokei", "scc", "repomix", "code2prompt"], "alternates": {"html": "https://wpnews.pro/news/i-built-a-cli-that-orients-you-in-an-unfamiliar-repo-feedback-wanted", "markdown": "https://wpnews.pro/news/i-built-a-cli-that-orients-you-in-an-unfamiliar-repo-feedback-wanted.md", "text": "https://wpnews.pro/news/i-built-a-cli-that-orients-you-in-an-unfamiliar-repo-feedback-wanted.txt", "jsonld": "https://wpnews.pro/news/i-built-a-cli-that-orients-you-in-an-unfamiliar-repo-feedback-wanted.jsonld"}}