Demo generated by code — python -m peek.tools.gen_demo (Pillow, no vhs) • also peek/assets/demo.svg + peek/assets/demo.html

peek — htop for codebases

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

Beautiful, zero-config codebase cartographer — Python-native, Rich + Textual, works offline.
peek scan • peek analyze • peek . (TUI) • peek --html • peek --pack • peek find • 10 themes

---

Install

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

# dev (with tests + demo generator)
pip install -e "peek[dev]"

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

Usage

1 — Interactive TUI (viral)

peek              # TUI on current dir
peek .            # same
peek /path/to/repo
peek --no-tui     # static Rich (for screenshots / CI / pipes)
peek --theme dracula
peek --theme-list # 10 themes

TUI keys: q quit • j/k nav • o open in $EDITOR • / filter • enter details • esc clear • ? help

2 — Static (tweet-ready) + HTML

peek --no-tui
peek analyze .
peek --html -o map.html && open map.html
peek --theme dracula --html -o report.html

3 — Pack, Find, LLM

# Smart LLM pack — top files within token budget
peek --pack                    # stdout → | pbcopy / clip
peek --pack --ask "auth"       # filtered
peek --pack -o pack.txt        # to file

# Find — keyword over filenames + content, ranked
peek find "auth" .
peek find "token validation" . --limit 10 --json

# LLM summary (optional, needs API key)
export OPENAI_API_KEY=sk-...
peek --llm

Demo (by code)

No vhs/ffmpeg needed — generated via Pillow:

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

Preview: peek/assets/demo.gif (15s, 145 frames, anthropic-pro #D4A27F→#141413), peek/assets/demo.svg (SMIL), peek/assets/demo.html (themed).

Features

Feature	scan	analyze	peek (TUI)
Walk respecting .gitignore	✅	✅	✅
Languages + LOC + by-lang bar	✅	✅	✅
Tech stack (pyproject.toml/package.json)	✅	✅	✅
Entry points (main.py/cli.py/__main__ guard)	✅	✅	✅
Import graph (AST, relative, src/ layout)	—	✅	✅
PageRank + in-degree + entry bonus ranking	—	✅	✅
Heuristic summary (FastAPI/Django/Typer…)	—	✅	✅
Textual TUI (nav, filter, open, 10 themes)	—	—	✅
--html / --pack / find / --llm	✅	✅	✅

10 Themes

peek --theme dracula
PEEK_THEME=tokyo-night peek
echo 'theme = "dracula"' > ~/.peek/config.toml
peek --theme-list

anthropic-pro (default, warm clay) • cinematic • dracula • nord • catppuccin-mocha • tokyo-night • solarized-dark • github-dark • monokai • minimal-mono — all 15 tokens #RRGGBB, validated at import.

Documentation

• Full manual: docs.md — Install, 10 Themes, CLI/TUI, Pack/Find/LLM, Config, Architecture, Testing, Troubleshooting
• Final state: master.md — UI fixes, TUI animations, themes, tests, demo video
• Research pack: docs/research/ — 8 docs that led to peek (viral thesis, candidates, 5-day plan, launch playbook)
• Specs & plans: docs/superpowers/ — theme system spec + implementation plans

Development

git clone https://github.com/hariomlohardev/peek && cd peek
pip install -e "peek[dev]"
pytest -q          # 113 passed, 1 skipped
peek --no-tui
peek              # TUI — q to quit, peek . also works
python -m peek.tools.gen_demo

See peek/CONTRIBUTING.md. ruff + pytest before PR. Branch v3 is the big upshift.

Contributing — Good First Issues

Want to contribute? We have 35 open issues tailored for every level — and they rank high on GitHub's good first issue search:

Browse all: https://github.com/hariomlohardev/peek/issues

• 20 Good First Issues (30 min, beginner): One file, copy-paste steps, good first issue + help wanted labels — e.g., docstrings, peek wtf --help example, peek --version test. Perfect for first PR!
• 10 Intermediate (60-90 min): tiktoken tokens, peek diff, peek serve, symbol index — needs a bit of design.
• 5 Complex (1-2 days): peek-mcp for Claude Code, polyglot tree-sitter, peek-vscode — for experienced contributors.

Every issue has exact file, acceptance checkboxes, and time estimate. PRs with good first issue get priority review and will be featured in release notes.

See peek/CONTRIBUTING.md for the full workflow. Branch v3 is where the big upshift lands (polyglot + semantic + MCP + graph).

Why peek?

Tool	Lacks
gitingest / repomix	No ranking, no graph, no TUI
pydeps / import-linter	No summary, no entry detection
tree / tokei / onefetch	No graph, no ranking

Moat: Every output is a screenshot. Every repo is a new demo. pip install peek-code is zero friction.

Author

Built by Hariom Lohar — hariomlohar.new@gmail.com

License

MIT — see peek/LICENSE and LICENSE if present