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 → languages, stack, Start Here, graph. Every output is a screenshot.

Install

pip install peek-code
pipx install peek-code          # or: uv tool install peek-code
pip install -e "peek[dev]" # dev — pyproject is at peek/pyproject.toml

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

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

peek wtf                  # paste traceback → explain with Start Here hint
cat tb.txt | peek wtf
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 · WTF → docs.md#wtf · Watch → docs.md#watch · Config → docs.md#config-set

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 5-col table + vs others → 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, Pack/Find/LLM, WTF, Watch, Config Set, Architecture, Testing
• Research: docs/research/ — viral thesis, candidates, 5-day plan
• Plans: docs/superpowers/

v2 Highlights

• peek wtf → traceback explainer, parses Traceback + Error + frames, Start Here hint — no LLM
• peek pack --format xml --budget 4000 --include "*.py" → token-smart pack v2 with budget and globs
• peek config set theme dracula → writes ~/.peek/config.toml, get/list validated via get_theme
• peek watch . / peek --watch (w toggle) → polling 0.8s / debounce 0.4s, watchfiles if installed
• t → live cycle 10 themes in TUI

Development

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

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

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