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 && peek .

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

Install

pip install peek
pipx install peek          # or: uv tool install peek
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
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

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

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, Config, Architecture, Testing
• Research: docs/research/ — viral thesis, candidates, 5-day plan
• Plans: docs/superpowers/

Development

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

See CONTRIBUTING.md. ruff + pytest before PR. Branch polish-100.

Why peek?

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

License

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