Demo by code — python -m peek.tools.gen_demo • also assets/demo.svg + assets/demo.html

peek — htop for codebases

Understand any codebase in 5 seconds. pip install peek-code && peek .

5 seconds → polyglot graph, languages, stack, Start Here. Every output is a screenshot.

Install

pip install peek-code
# or
pipx install peek-code
uv tool install peek-code

# dev (with tests + demo generator) — from repo root:
pip install -e "./peek[dev]"
# or from peek/: pip install -e ".[dev]"

Requires Python 3.11+. Deps: typer, rich, textual, pathspec.

Full install → docs.md

Quick Start

peek                      # TUI — q quit, / filter, j/k nav, o open, t cycle, w watch
peek --no-tui             # static Rich (CI / screenshot)
peek --theme dracula --html -o map.html && open map.html
peek graph --format svg -o graph.svg  # polyglot import graph → DOT/SVG/HTML
peek find "auth token" --semantic     # semantic BM25 (+ fastembed) — multi-word = intent
peek mcp                  # MCP server for Claude Code / any MCP client
peek trace --html                  # function tree → browser (filter, theme, expand, copy)

Keys: q quit • j/k nav • o open $EDITOR • / filter • enter details • esc clear • ? help • t theme • w watch

peek trace scan --depth 3              # terminal tree: what it takes & where it goes
peek trace scan --html -o trace.html      # polished HTML + browser (filter, theme, expand)
peek trace --at peek/scanner.py:601 --depth 2 --local  # pinpoint via file:line
peek wtf                  # paste traceback → explain with Start Here hint
peek watch .              # live rescan on file change (polling, Ctrl+C)
peek config set theme dracula  # persists

Full CLI → docs.md#cli-reference · TUI → docs.md#tui-guide · Semantic → docs.md#semantic

GitHub Action

- uses: hariomlohardev/peek@v1   # posts Start Here as a PR comment (outputs: start-here, summary)
  with:
    path: .

Example workflow → .github/workflows/peek.yml · Full guide → docs.md#github-action

Demo (by code)

python -m peek.tools.gen_demo        # → peek/assets/demo.gif (800×450, <3MB) + demo.svg
peek --html -o peek/assets/demo.html
pytest peek/tests/test_demo_assets.py -v

How it works → docs.md#demo-video

Features

Full table → docs.md#features

10 Themes

peek --theme dracula
peek --theme-list  # anthropic-pro (default), cinematic, dracula, nord, catppuccin-mocha, tokyo-night, solarized-dark, github-dark, monokai, minimal-mono

Warm clay anthropic-pro → neon cinematic → dracula → nord. 15 tokens #RRGGBB, precedence cli > PEEK_THEME > config > anthropic-pro.

Full table + previews → docs.md#10-themes

Documentation

• Full manual: docs.md — Install, Demo, Features, Themes, CLI, TUI, Symbols, Semantic, Graph, Git, MCP, WTF, Watch, Config

v3 Highlights

• polyglot graph — Python AST + JavaScript/TypeScript import/require regex, peek graph --format svg
• semantic BM25 (peek/embeddings.py) + fastembed, peek find "auth token" --semantic, peek --pack --ask "auth token" --semantic
• pack 3.0 — --clip/--dry-run/--diff HEAD/--staged, URL fetch, tiktoken; peek mcp stdio server for Claude Code

v2 Highlights

• peek wtf / peek pack v2 --format xml --budget 4000 / peek config set theme dracula / peek watch . (w toggle) / t theme cycle

Development

git clone https://github.com/hariomlohardev/peek && cd peek
pip install -e ".[dev]"
pytest -q          # 146 passed, 1 skipped
peek --no-tui && peek  # static + TUI

See CONTRIBUTING.md. ruff + pytest before PR. Branch v3.

Contributing — Good First Issues

New to open source? Start here — 20 good first issues, each ~30 min, one file, copy-paste steps:

Browse: https://github.com/hariomlohardev/peek/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22

• Beginner (30 min): docstrings, typo fixes, --help examples, peek --version test — pick any, no setup beyond pip install -e ".[dev]"
• Intermediate (60-90 min): tiktoken tokens, peek diff, peek serve, symbol index
• Complex (1-2 days): peek-mcp for Claude Code, polyglot tree-sitter, semantic embeddings, peek-vscode

Every issue has exact file, acceptance checkboxes, and pytest -q gate. PRs with good first issue label get priority review.

See CONTRIBUTING.md for ruff + pytest workflow. Branch v3 is the big upshift (polyglot + semantic + MCP).

Why peek?

Every output is a screenshot. Every repo is a new demo. pip install peek-code is zero friction — unlike gitingest (no ranking) or pydeps (no TUI).

License

MIT — LICENSE · Built by Hariom Lohar — hariomlohar.new@gmail.com